# Troubleshooting symbol file uploads from CI/CD pipelines

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

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)](#401-unauthorized)
* [Token fetch fails (403 Forbidden)](#403-forbidden)
* [Script exits with "Path validation failed"](#path-validation-failed)
* [Usymtool prints "Unity Cloud Diagnostics credentials unavailable"](#credentials-unavailable)
* [Usymtool prints "Signed URL request failed with status: 401"](#signed-url-request-failed)
* [Crash reports aren't symbolicated](#reports-missing-symbols)
* [Usymtool logs "File already exists" or returns status 409](#file-already-exists)
* [Usymtool warns "no symbol section" or "decoding dwarf section info... too short" (Android)](#stripped-symbol-files)
* [Usymtool warns "no C# lines were successfully mapped to C++ lines"](#no-lines-mapped)
* [Usymtool fails with "lzma: e: No such file or directory" (Unity 6.2 and earlier)](#no-such-file)
* ["File exists" error during compression on retry](#file-exists-compression)

## Token fetch fails (401 Unauthorized)##401-unauthorized

When you call the token API, you receive an HTTP `401 Unauthorized` client error response.

1. **Cause**

   This error occurs when your service account credentials are expired or incorrect.

2. **Resolution**

   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)##403-forbidden

When you call the token API, you receive an HTTP `403 Forbidden` client error response.

1. **Cause**

   This error occurs when the service account is missing the required permissions at the project level.

2. **Resolution**

   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"##path-validation-failed

When you run the `usymtool` script, the script exits with the error message "Path validation failed."

1. **Cause**

   This error occurs when one or more required paths don't exist on your machine.

2. **Resolution**

   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"##credentials-unavailable

The `usymtool` script prints the error message "Unity Cloud Diagnostics credentials unavailable."

1. **Cause**

   This error occurs when the upload token is empty. Under normal circumstances, the script automatically fetches the upload token.

2. **Resolution**

   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"##signed-url-request-failed

The `usymtool` script prints the error message "Signed URL request failed with status: 401."

1. **Cause**

   The upload token is invalid or expired. Tokens expire after seven days.

2. **Resolution**

   To resolve the issue, rerun the script. The script automatically fetches a fresh token.

## Crash reports aren't symbolicated##reports-missing-symbols

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>`.

1. **Cause**

   This error occurs when the uploaded symbols' universally unique identifiers (UUIDs) don't match the binary that crashed.

2. **Resolution**

   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##file-already-exists

This message appears when an existing symbol file is reuploaded to the Dashboard. This behavior is expected and not an error.

1. **Cause**

   The server returns an HTTP 409 status code when  `usymtool` skips a symbol file that has already been uploaded.

2. **Resolution**

   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"##stripped-symbol-files

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)

1. **Cause**

   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.

2. **Resolution**

   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"##no-lines-mapped

When the script runs `usymtool`, it returns the following error message:

```text
level=warning msg="Warning: -il2cppOutputPath was provided, but no C# lines were
successfully 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"
```

1. **Cause: Mismatched values and file paths**

   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.

2. **Resolution**

   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](#stripped-symbol-files).

1) **Cause: Known limitation in Unity 6.2 and earlier**

   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.

2) **Resolution**

   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](/cloud/developer-data/upload-symbol-files-ci.md#override-derived-paths).

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

This message appears after `usymtool` finishes processing the symbols, but before it uploads them.

1. **Cause**

   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.

2. **Resolution**

   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##file-exists-compression

This message appears after `usymtool` finishes processing the symbols, but before it uploads them.

1. **Cause**

   If a previous upload failed during compression, then stale temporary files in `/tmp/usym_upload/` can block the next run.

2. **Resolution**

   To remove stale temporary files, clear the directory and retry the following command:

   ```bash
   rm -rf /tmp/usym_upload/
   ```