Troubleshooting symbol file uploads from CI/CD pipelines

Solve common problems with uploading debugging symbols from CI/CD pipelines.

Read time 5 minutes

Last updated 6 hours 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.

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:

Check the script output preceding the error for token extraction failures.
Confirm that the value for
```
USYM_UPLOAD_AUTH_TOKEN
```
is entered correctly.
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.

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:

Check that the UUID reported on the Dashboard matches the UUID reported by
```
usymtool
```
in its upload logs.
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.

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:

Check the warning message for the

most common C++ file root

hint. For example,

/UnityProjects/UsymtoolLogsTest/Library/Bee/artifacts/MacStandalonePlayerBuildProgram/il2cppOutput/cpp

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:

Copy the
```
usymtool
```
binary from an installation of Unity 6.3 or later.
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

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

<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/

Documentation

Development

User Acquisition

Monetization

Industry

Unity Cloud

Get Started

Asset Manager SDKs and services

Unity Cloud

Troubleshooting symbol file uploads from CI/CD pipelines

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