Troubleshooting

This guide helps you diagnose and resolve common issues with the Sentry CLI.

Common Issues

Authentication Problems

Error: Not authenticated. Run 'sentry auth login' first.

Cause: The CLI cannot find a valid authentication token.Solutions:

Log in with OAuth:
```
sentry auth login
```

Use an environment variable:

export SENTRY_AUTH_TOKEN=your_token_here
sentry auth status

Use a token file (for CI/CD):

echo "your_token_here" > ~/.sentry-token
export SENTRY_AUTH_TOKEN=$(cat ~/.sentry-token)

Note: SENTRY_AUTH_TOKEN takes precedence over SENTRY_TOKEN and stored OAuth tokens.

Error: Authentication expired. Run 'sentry auth login' to re-authenticate.

Cause: Your OAuth token has expired and cannot be refreshed.Solutions:

Re-authenticate:
```
sentry auth login
```

Check token expiration:

sqlite3 ~/.config/sentry-cli/config.db \
  "SELECT datetime(expires_at/1000, 'unixepoch') AS expires FROM auth WHERE id = 1;"

Use a non-expiring token (for automation):
- Go to Sentry → Settings → Account → Auth Tokens
- Create a new auth token
- Set SENTRY_AUTH_TOKEN environment variable

Error: Session expired and no refresh token available.

Cause: The stored OAuth token expired and there’s no refresh token to renew it.Solution: Re-authenticate using the login command:

sentry auth login

This error typically happens if:

You manually edited the database
The OAuth flow was interrupted
The token was created before refresh token support was added

Context Resolution

Error: Organization is required.

Cause: The CLI cannot determine which organization to use.Solutions:

Specify explicitly:
```
sentry issue list my-org
```
Set default organization:
```
export SENTRY_ORG=my-org
```

Use DSN detection:

Add a Sentry DSN to .env in your project:

SENTRY_DSN=https://[email protected]/7890123

Or add it to your code (JavaScript example):

Sentry.init({
  dsn: "https://[email protected]/7890123",
});

Store a default:
```
sentry defaults set my-org
```

Error: Organization and project are required.

Cause: The CLI needs both org and project context but cannot determine them.Solutions:

Specify explicitly:
```
sentry issue list my-org/my-project
```

Set environment variables:

export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-project

Use DSN detection (see above)
Store defaults:
```
sentry defaults set my-org/my-project
```

Database Errors

Error: attempt to write a readonly database

Cause: The CLI cannot write to its SQLite database due to permission issues.Solutions:

Check file permissions:

ls -la ~/.config/sentry-cli/
chmod 700 ~/.config/sentry-cli/
chmod 600 ~/.config/sentry-cli/config.db

Check directory permissions:

# Ensure the parent directory is writable
ls -la ~/.config/

Check if filesystem is read-only:

mount | grep "$(df ~/.config/sentry-cli | tail -1 | awk '{print $1}')"

Use a custom config directory:

export SENTRY_CONFIG_DIR=~/custom-sentry-config
mkdir -p ~/custom-sentry-config

Error: no such table: [table_name]

Cause: The database schema is corrupted or incomplete.Solutions:

Let auto-repair fix it (default behavior):
- The CLI automatically detects and repairs schema issues
- Check the logs for “Auto-repaired database” messages
Manual repair:
```
sentry cli fix
```

Reset the database (last resort):

rm ~/.config/sentry-cli/config.db
# The CLI will recreate it on next run

Note: Auto-repair can be disabled with SENTRY_CLI_NO_AUTO_REPAIR=1 (not recommended).

Error: no such column: [column_name]

Cause: The database schema is outdated (usually after downgrading the CLI).Solutions:

Upgrade to the latest CLI version:
```
sentry upgrade
```
Let auto-repair add the column (automatic in most cases)
Reset the database:
```
rm ~/.config/sentry-cli/config.db
```

API Errors

Error: Request failed with status 401

Cause: Authentication failed (invalid or expired token).Solutions:

Check token validity:
```
sentry auth status
```
Re-authenticate:
```
sentry auth login
```
Verify token permissions (for auth tokens):
- Go to Sentry → Settings → Auth Tokens
- Ensure the token has the required scopes
- Check if the token is enabled and not expired

Error: Request failed with status 403

Cause: You don’t have permission to access the requested resource.Solutions:

Check organization/project access:
- Verify you’re a member of the organization
- Check your role (some commands require admin/owner)
Verify auth token scopes:
- Org auth tokens may have limited scopes
- Use a user auth token or re-create the org token with broader scopes

Check if the resource exists:

sentry org view my-org
sentry project view my-org/my-project

Error: Request failed with status 404

Cause: The requested resource (org, project, issue, etc.) doesn’t exist or you don’t have access.Solutions:

Verify the resource exists:

# List organizations
sentry org list

# List projects
sentry project list my-org

# Check issue ID format
sentry issue view SENTRY-123

Check spelling:
- Slugs are case-sensitive
- Use the exact slug from the Sentry web UI
Verify you have access:
- You may not be a member of the organization
- The project may be in a different organization

Self-Hosted Sentry

Error: OAuth requires SENTRY_CLIENT_ID for self-hosted instances

Cause: OAuth device flow requires a client ID for self-hosted Sentry (version 26.1.0+).Solution:

Create an OAuth application:
- Go to your Sentry instance → Settings → Developer Settings
- Click “Create New Application”
- Select “Public” application type
- Copy the client ID

Set the environment variables:

export SENTRY_URL=https://sentry.example.com
export SENTRY_CLIENT_ID=your-oauth-client-id

Log in:
```
sentry auth login
```

Alternative (for older Sentry versions):

sentry auth login --token

Debugging Techniques

Enable Debug Logging

Get detailed information about what the CLI is doing:

# Using environment variable
export SENTRY_LOG_LEVEL=debug
sentry issue list

# Using flag
sentry --log-level debug issue list

# Using --verbose (equivalent to debug level)
sentry --verbose issue list

Log levels:

error: Only errors
warn: Errors and warnings
info: Normal output (default)
debug: Detailed debugging information
trace: Very verbose (includes HTTP requests/responses)

Inspect the Database

Query the SQLite database directly:

sqlite3 ~/.config/sentry-cli/config.db

-- Check authentication status
SELECT 
  token IS NOT NULL AS has_token,
  refresh_token IS NOT NULL AS has_refresh_token,
  datetime(expires_at/1000, 'unixepoch') AS expires,
  datetime(updated_at/1000, 'unixepoch') AS updated
FROM auth WHERE id = 1;

-- View defaults
SELECT organization, project 
FROM defaults WHERE id = 1;

-- Check schema version
SELECT version FROM schema_version;

-- List all tables
.tables

-- View table schema
.schema project_cache

Test DSN Detection

Check if the CLI can detect your project’s DSN:

# From your project directory
sentry auth status
# Look for "Detected from: .env" or "Detected from: src/index.js"

# Force DSN detection
unset SENTRY_ORG
unset SENTRY_PROJECT
sentry issue list

Check Network Connectivity

Verify you can reach the Sentry API:

# SaaS
curl -I https://sentry.io/api/

# Self-hosted
curl -I https://your-sentry-instance.com/api/

Verify Token Format

Sentry auth tokens have specific formats:

User auth tokens: Start with sntryu_
Org auth tokens: Start with sntrys_
OAuth access tokens: Random alphanumeric (40+ characters)

# Check token format
echo $SENTRY_AUTH_TOKEN | cut -c1-7
# Should show "sntryu_" or "sntrys_"

Error Message Reference

CliError

Base class for all CLI errors. Generic format:

Error: [message]

ApiError

API request failures. Format:

Error: [summary]
  [detailed message from API]

Common Status Codes:

400: Bad request (invalid parameters)
401: Unauthorized (authentication failed)
403: Forbidden (insufficient permissions)
404: Not found
429: Rate limited
500: Internal server error

AuthError

Authentication failures. Reasons:

not_authenticated: No valid token found
expired: Token has expired
invalid: Token is malformed or rejected

ConfigError

Configuration issues. Format:

Error: [message]

Suggestion: [helpful hint]

ContextError

Missing required context (org/project). Format:

[Resource] is required.

Specify it using:
  [command example]

Or:
  - [alternative 1]
  - [alternative 2]

ResolutionError

Failed to resolve a resource. Format:

[Resource] [headline].

Try:
  [primary hint]

Or:
  - [suggestion 1]
  - [suggestion 2]

ValidationError

Invalid input. Format:

Error: [validation message]

DeviceFlowError

OAuth device flow failures. Common codes:

authorization_pending: User hasn’t authorized yet
slow_down: Polling too fast
expired_token: Device code expired
access_denied: User denied authorization

SeerError

Seer AI feature errors. Reasons:

not_enabled: Seer not enabled for the organization
no_budget: Requires a paid plan
ai_disabled: AI features disabled in organization settings

Format includes actionable URLs:

[message]

[direct link to relevant settings]

UpgradeError

CLI upgrade failures. Reasons:

unknown_method: Cannot detect installation method
unsupported_operation: Operation not supported for this install method
network_error: Failed to fetch version info
execution_failed: Upgrade command failed
version_not_found: Specified version doesn’t exist

Performance Issues

Slow command execution

Possible Causes:

Network latency to Sentry API
Large result sets (e.g., listing thousands of issues)
Slow DSN detection (scanning many files)

Solutions:

Use pagination:

sentry issue list --limit 25  # Reduce result set

Skip DSN detection:

export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-project

Use regional endpoints (automatic for SaaS):
- The CLI automatically detects and uses regional APIs
- Check org_regions table for cached regions
Check network latency:
```
time curl -I https://sentry.io/api/
```

High memory usage

Possible Causes:

Large API responses
Caching many projects

Solutions:

Clear caches:

sqlite3 ~/.config/sentry-cli/config.db \
  "DELETE FROM project_cache; DELETE FROM dsn_cache;"

Use streaming mode (for large result sets):
```
sentry issue list --json | jq -c '.[]'
```

Getting Help

If you’re still experiencing issues:

Check the documentation:
Enable debug logging:
```
sentry --log-level debug [command]
```
Report a bug:
- GitHub Issues: github.com/getsentry/sentry-cli
- Include:
  - CLI version (sentry --version)
  - Operating system
  - Error message and full command
  - Debug logs (with sensitive data redacted)
Get community support:
- Sentry Discord: discord.gg/sentry
- Sentry Forum: forum.sentry.io

Integrations

Reference

Common Issues

Authentication Problems

Context Resolution

Database Errors

API Errors

Self-Hosted Sentry

Debugging Techniques

Enable Debug Logging

Inspect the Database

Test DSN Detection

Check Network Connectivity

Verify Token Format

Error Message Reference

CliError

ApiError

AuthError

ConfigError

ContextError

ResolutionError

ValidationError

DeviceFlowError

SeerError

UpgradeError

Performance Issues

Getting Help

Build docs developers (and LLMs) love

Integrations

Reference

​Common Issues

​Authentication Problems

​Context Resolution

​Database Errors

​API Errors

​Self-Hosted Sentry

​Debugging Techniques

​Enable Debug Logging

​Inspect the Database

​Test DSN Detection

​Check Network Connectivity

​Verify Token Format

​Error Message Reference

​CliError

​ApiError

​AuthError

​ConfigError

​ContextError

​ResolutionError

​ValidationError

​DeviceFlowError

​SeerError

​UpgradeError

​Performance Issues

​Getting Help

Build docs developers (and LLMs) love

Common Issues

Authentication Problems

Context Resolution

Database Errors

API Errors

Self-Hosted Sentry

Debugging Techniques

Enable Debug Logging

Inspect the Database

Test DSN Detection

Check Network Connectivity

Verify Token Format

Error Message Reference

CliError

ApiError

AuthError

ConfigError

ContextError

ResolutionError

ValidationError

DeviceFlowError

SeerError

UpgradeError

Performance Issues

Getting Help