Skip to content

feat(rust): add troubleshooting page #14595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: lcian/feat/rust-tracing-docs
Choose a base branch
from
Open

feat(rust): add troubleshooting page #14595

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/platforms/rust/common/troubleshooting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
title: Troubleshooting
sidebar_order: 9000
description: "If you need help solving issues with the Sentry Rust SDK, you can read the edge cases documented below."
---

As a first step to debug any issue with the SDK, you should perform initialization with `debug: true` in your `ClientOptions` struct passed to `sentry::init`.
Copy link
Contributor

@coolguyzone coolguyzone Aug 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
As a first step to debug any issue with the SDK, you should perform initialization with `debug: true` in your `ClientOptions` struct passed to `sentry::init`.
To start debugging any SDK issue, enable debug mode by setting debug: true in the ClientOptions struct you pass to sentry::init.

This will make the SDK log additional debug information on stderr.

Read below to find a list of common problems and how to solve them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Read below to find a list of common problems and how to solve them.
Below is a list of common problems and how to solve them.


## General

<Expandable title="Panic on SDK initialization">
The SDK has been reported to panic on initialization when using the `debug-images` feature on machines with specific versions of the Linux kernel due to an issue with one of its dependencies.
Copy link
Contributor

@alexander-alderman-webb alexander-alderman-webb Aug 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what the conventions in the Sentry docs are but I try to avoid passive language when possible.

Also, are you sure it has to do with the kernel? Because I don't think the kernel has dependencies in that sense, but potentially there is a problem with kernel modules or graphics drivers? If not, I would use some more generic term like below so users submit all potentially relevant information.

Suggested change
The SDK has been reported to panic on initialization when using the `debug-images` feature on machines with specific versions of the Linux kernel due to an issue with one of its dependencies.
Users have reported SDK initialization to panic when using the `debug-images` feature on machines with specific Linux platforms.


Please open a GitHub [issue](https://github.com/getsentry/sentry-rust/issues/new/choose) with your OS and kernel version if you're affected by this.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would graphics card drivers be relevant here? I think it might be worth asking for them as well

</Expandable>

<Expandable title="Duplicated stack frames">
There's an issue where stack frames can appear to be duplicated in Sentry with respect to the real stack trace.
As there's a currently a hard limit of 200 frames in ingestion, this can cause errors to be missing stack frames when the limit is exceeded.
This happens when the stack trace is already symbolicated on the client (due to debug information being present at runtime) but gets resymbolicated on the server.

There are two alternative ways to address this problem:
- keep debug information in the binary, but disable the `debug-images` feature of the `sentry` crate;
- strip debug information from the binary, and [upload debug files](/platforms/rust/source-context/#compile-and-create-debug-information-files) separately.
</Expandable>


<Expandable title="'This frame has an unknown problem and can not be symbolicated' error in the UI for application stack frames">
This can happen when your executable doesn't have a build ID, and therefore stack frames cannot be associated with any debug files by the Sentry backend.

To ensure `cargo` embeds a build ID in your binary, set the following environment variable when building: `RUSTFLAGS="-Clink-args=-Wl,--build-id"`.
</Expandable>