Documentation

​
​

Development

User Acquisition

Monetization

Industry

Unity Cloud

Get Started

Asset Manager SDKs and services

Open Unity Dashboard

Unity Cloud

​
​
Unity Dashboard
  • Accounts
  • Organizations
  • Projects
  • Products
  • Billing
Developer Data
  • Introduction to the Developer Data Framework
  • Get started
  • View Diagnostics for your project
    • Access Diagnostics
    • View events leading to a crash
    • Manage reports
      • Set up custom reports
      • Test reports
      • Debugging symbols
        • Introduction to debugging symbols
        • Upload symbol files through the Unity Dashboard
        • Upload debugging symbols from CI/CD pipelines
        • Runner examples for uploading debugging symbols through CI/CD pipelines
        • Troubleshooting symbol file uploads from CI/CD pipelines
        • Symbol file uploads API reference
    • Diagnostics page reference
  • Privacy and consent
Unity Asset Manager
  • What's new
  • Asset Manager web
  • Asset Store
  • Manage Assets in the Editor
  • Unity Version Control
  • Developer documentation
Unity Pipeline Automation
  • About
  • Get started
  • Pipelines
  • Automations
  • Monitor jobs
  1. Unity Cloud Documentation
  3. Developer Data framework

Troubleshooting symbol file uploads from CI/CD pipelines

Solve common problems with uploading debugging symbols from CI/CD pipelines.
Read time 7 minutes
Last updated 3 months ago
If you experience errors when you upload symbol files directly from CI/CD pipelines, then refer to the following sections for information about how to resolve each type of error:
  • Token fetch fails (401 Unauthorized)
  • Token fetch fails (403 Forbidden)
  • Script exits with "Path validation failed"
  • Usymtool prints "Unity Cloud Diagnostics credentials unavailable"
  • Usymtool prints "Signed URL request failed with status: 401"
  • Crash reports aren't symbolicated
  • Usymtool logs "File already exists" or returns status 409
  • Usymtool warns "no symbol section" or "decoding dwarf section info... too short" (Android)
  • Usymtool warns "no C# lines were successfully mapped to C++ lines"
  • Usymtool fails with "lzma: e: No such file or directory" (Unity 6.2 and earlier)
  • "File exists" error during compression on retry

Token fetch fails (401 Unauthorized)

When you call the token API, you receive an HTTP 
401 Unauthorized
client error response.
This error occurs when your service account credentials are expired or incorrect.
To find and resolve the issue, verify the following:
  • The Service Account API key hasn't expired or been revoked.
  • The 
    UNITY_SERVICE_ACCOUNT_AUTH_HEADER
    value is the Authorization header copied directly from the Dashboard. For example, 
    Basic MmZiM2Zh...
    .
  • No extra whitespace or newlines were added when pasting the value.

Token fetch fails (403 Forbidden)

When you call the token API, you receive an HTTP 
403 Forbidden
client error response.
This error occurs when the service account is missing the required permissions at the project level.
To find and resolve the issue, verify the following:
  • The Observability Symbols Uploader role is assigned to your service account for the target project.
  • The role is assigned at the project level, not only at the organization level.

Script exits with "Path validation failed"

When you run the 
usymtool
script, the script exits with the error message "Path validation failed."
This error occurs when one or more required paths don't exist on your machine.
To find and resolve the issue, verify the following:
  • UNITY_EDITOR_PATH
    points to a valid Unity Editor installation.
  • Your build has completed and produced symbol files at the expected path.
  • For IL2CPP builds, the IL2CPP output directory exists.

Usymtool prints "Unity Cloud Diagnostics credentials unavailable"

The 
usymtool
script prints the error message "Unity Cloud Diagnostics credentials unavailable."
This error occurs when the upload token is empty. Under normal circumstances, the script automatically fetches the upload token.
To find and resolve the issue, follow these steps:
  1. Check the script output preceding the error for token extraction failures.
  2. Confirm that the value for 
    USYM_UPLOAD_AUTH_TOKEN
    is entered correctly.
  3. If the token is expired, rerun the script to fetch a fresh token.

Usymtool prints "Signed URL request failed with status: 401"

The 
usymtool
script prints the error message "Signed URL request failed with status: 401."
The upload token is invalid or expired. Tokens expire after seven days.
To resolve the issue, rerun the script. The script automatically fetches a fresh token.

Crash reports aren't symbolicated

After you upload your symbol files, crash reports in the Dashboard still show raw addresses instead of function names. The Dashboard displays an error message that symbols are missing. For example, 
<symbols missing for uuid: b809799c0ec93ee1b730342bdbf14e03>
.
This error occurs when the uploaded symbols' universally unique identifiers (UUIDs) don't match the binary that crashed.
To find and resolve the issue, follow these steps:
  1. Check that the UUID reported on the Dashboard matches the UUID reported by 
    usymtool
    in its upload logs.
  2. If the UUIDs don't match, then rebuild and reupload symbols from the exact same build.

Usymtool logs "File already exists" or returns status 409

This message appears when an existing symbol file is reuploaded to the Dashboard. This behavior is expected and not an error.
The server returns an HTTP 409 status code when 
usymtool
skips a symbol file that has already been uploaded.
If you need to reupload a symbol file that already exists in the Dashboard, then use one of the following methods:
  • Add 
    -forceUpload
    to the 
    FILTER_OVERRIDE
    .
  • Manually append 
    -forceUpload
    to the 
    usymtool
    command in the script.

Usymtool warns "no symbol section" or "decoding dwarf section info... too short"

When the 
usymtool
script attempts to process a symbol file, it returns one of the following error messages:
  • no symbol section
  • ELF binary has no symbol table — skipping
    (Android, Linux)
  • Mach-O binary contains a valid UUID but no symbols — skipping
    (Apple platforms)
  • PDB file contains a valid GUID but no symbol data — skipping
    (Windows)
  • decoding dwarf section info at offset 0x0: too short
    (Android, Linux, Apple)
These errors occur when the uploaded .so files contain valid UUIDs but no debug information. These symbol files are considered "stripped." On Android, the default symbol path (
Library/Bee/Android/Prj/IL2CPP/Gradle/unityLibrary/symbols/
) contains stripped .so files that are intended for the APK.
Although The 
usymtool
tool accepts and uploads stripped files without reporting an error, the symbols don't help with crash symbolication due to missing debug information.
To get .so files with debug data, you must configure your project settings before you begin to build in the Unity Editor. Turn on one or both of the following settings in the Editor:
  • In Player Settings > Android > Publishing Settings, turn on "Create symbols.zip".
  • In Build Profiles, turn on Debug Symbols.
Note
These Unity Editor project settings can't be enabled from CI flags or command-line parameters. If you use 
game-ci/unity-builder
or another CI build action, you must turn on the setting in your Unity project before you start the build.

Usymtool warns "no C# lines were successfully mapped to C++ lines"

When the script runs 
usymtool
, it returns the following error message:
level=warning msg="Warning: -il2cppOutputPath was provided, but no C# lines weresuccessfully mapped to C++ lines. Are the values for -il2cppOutputPath and-il2cppFileRoot correct? The most common C++ file root in the symbol file was <path>,try using that instead"
This error occurs when the 
-il2cppFileRoot
value doesn't match the C++ file paths embedded in the symbol file. Without a match, 
usymtool
can't map C++ stack frames back to C# source lines.
To find and resolve this issue, follow these steps:
  1. Check the warning message for the 
    most common C++ file root
    hint. For example, 
    /UnityProjects/UsymtoolLogsTest/Library/Bee/artifacts/MacStandalonePlayerBuildProgram/il2cppOutput/cpp
    .
  2. In the script's ADVANCED section, enter this path on the 
    IL2CPP_FILE_ROOT_OVERRIDE
    line.
Note
If the symbol file embeds relative paths, then you can use 
IL2CPP_FILE_ROOT_OVERRIDE="."
instead.
If you still encounter the warning after you enter the correct 
il2cppFileRoot
value, then verify that your .so files aren't missing debug information that the line mapping needs to function. For more information, refer to resolving stripped symbol files.
The 
usymtool
binary bundled with Unity 6.2 and earlier is built with an older Go compiler that can't correctly parse DWARF debug data for C# line mapping.
If you use one of these Unity versions, the following issues occur even with valid unstripped symbols and correct paths:
  • usymtool
    gives the warning that "no C# lines were successfully mapped to C++ lines."
  • C# file and line information is missing from crash reports.
To resolve this issue, follow these steps:
  1. Copy the 
    usymtool
    binary from an installation of Unity 6.3 or later.
  2. Use 
    USYMTOOL_PATH_OVERRIDE
    to point to the new 
    usymtool
    binary.
For more information about using path overrides, refer to Override derived paths.

Usymtool fails with "lzma: e: No such file or directory" (Unity 6.2 and earlier)

This message appears after 
usymtool
finishes processing the symbols, but before it uploads them.
This error occurs only on Unity 6.2 and earlier, because these versions depend on an external 
lzma
binary for compression.
GNU 
lzma
doesn't support the encode 
e
subcommand that the LZMA SDK uses. When GNU 
lzma
is on your 
PATH
, it shadows Unity's bundled binary, and the compression step fails.
Note
This error doesn't occur on Unity 6.3 and later. Newer versions of Unity use built-in 
gzip
compression, and no longer depend on an external 
lzma
binary.
The script sets 
LZMA_PATH
automatically to point to Unity's bundled 
lzma
at 
<UNITY_EDITOR_PATH>/Unity.app/Contents/Tools/macosx/lzma
. If you're building a custom integration without the script, then export this variable before you run 
usymtool
.

"File exists" error during compression on retry

This message appears after 
usymtool
finishes processing the symbols, but before it uploads them.
If a previous upload failed during compression, then stale temporary files in 
/tmp/usym_upload/
can block the next run.
To remove stale temporary files, clear the directory and retry the following command:
rm -rf /tmp/usym_upload/
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S and elsewhere (more info here). Other names or brands are trademarks of their respective owners.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.

  • On this page

    • Token fetch fails (401 Unauthorized)

    • Token fetch fails (403 Forbidden)

    • Script exits with "Path validation failed"

    • Usymtool prints "Unity Cloud Diagnostics credentials unavailable"

    • Usymtool prints "Signed URL request failed with status: 401"

    • Crash reports aren't symbolicated

    • Usymtool logs "File already exists" or returns status 409

    • Usymtool warns "no symbol section" or "decoding dwarf section info... too short"

    • Usymtool warns "no C# lines were successfully mapped to C++ lines"

    • Usymtool fails with "lzma: e: No such file or directory" (Unity 6.2 and earlier)

    • "File exists" error during compression on retry

Report a problem with this page