Troubleshooting

Common fixes for installation, authentication, and runtime problems when working with RAPS🌼RAPSRust CLI for Autodesk Platform Services.View in glossary.

Installation issues

• Command▶️CommandInstruction executed by a CLI tool.View in glossary not found — confirm raps is on your PATH. On Windows, reopen your terminal🖥️TerminalApplication for running command-line programs.View in glossary after Scoop/PowerShell installs; on macOS/Linux ensure /usr/local/bin or your chosen install directory is in PATH.
• Outdated binary — run raps --version and reinstall from Releases or your package manager if the version is below the one referenced in docs/blog posts.
• Missing SSL certificates — container📦ContainerIsolated, portable application environment.View in glossary images or minimal distros may not ship CA bundles. Install ca-certificates (Debian/Ubuntu) or ca-certificates-utils (Arch) to allow OAuth🔐OAuthIndustry-standard authorization protocol used by APS.View in glossary traffic.

Authentication problems

• Invalid client credentials🤖2-legged authServer-to-server authentication without user context.View in glossary — re-copy the APS_CLIENT_ID and APS_CLIENT_SECRET from the APS Developer Portal and run raps auth test. Clipboard whitespace or swapped values are the most common causes of 401 responses.
• Device code timeouts — if SSO approval takes too long, use raps auth login --force-pkce to trigger an interactive PKCE flow in the browser instead of the device code loop.
• Multiple profiles — raps config profile list shows which profile👤ProfileNamed set of configuration settings.View in glossary is active. Use raps config profile use staging (or another name) before running commands to avoid mixing sandbox and production tokens.

Authorization and permissions

• 403 Forbidden — verify the APS☁️APSAutodesk Platform Services - cloud APIs for CAD/BIM automation.View in glossary app has the correct scopes for the API🔌APIInterface for software components to communicate.View in glossary you are calling. For bucket🪣BucketContainer for storing objects in OSS.View in glossary/object operations you typically need data:read, data:write, and bucket:create scopes.
• ACC🏗️ACCAutodesk's construction management platform.View in glossary/BIM 360🔵BIM 360Legacy Autodesk construction platform (predecessor to ACC).View in glossary access — ensure the APS app is added to the BIM🏛️BIMIntelligent 3D model-based design for buildings.View in glossary 360 account with the right role. Without admin approval, folder or issue queries will return empty lists.
• Region mismatches — list your buckets with raps bucket list --region us or --region emea to ensure uploads and translations happen in the correct region.

Security and token storage (v3.7.0+)

• Keychain🔑KeychainSecure OS storage for credentials.View in glossary access errors — if you get “access denied” errors with keychain storage, run raps config set use_keychain false to temporarily use file storage while diagnosing keychain issues.
• Token🎟️TokenCredential for API authentication.View in glossary migration — when upgrading from v3.6.x or earlier, run raps config migrate-tokens to move existing tokens from file storage to secure keychain storage.
• Headless environments — in Docker🐳DockerContainer platform for consistent environments.View in glossary containers or CI🔁CI/CDAutomated build, test, and deployment pipelines.View in glossary environments without keychain support, use RAPS_USE_FILE_STORAGE=true environment variable🌍Environment VariableConfiguration value passed to applications.View in glossary to enable file-based token storage.

Workflow reliability

• Large uploads — switch🚩FlagOptional parameter modifying command behavior.View in glossary to multipart uploads with raps object upload my-bucket model.rvt --multipart --chunk-size 16MB to avoid timeouts over slow networks.
• Translation⚙️Translation JobBackground process converting CAD files to viewable formats.View in glossary stuck in pending — use raps translate status $URN --wait --interval 10 to poll and surface errors. If status stays pending, re-run with the correct input format flag (e.g., --format svf2).
• CI/CD flakiness — enable verbose logs with RAPS_LOG=debug in your workflow📈WorkflowAutomated process triggered by events.View in glossary and check for retryable HTTP🔗HTTPProtocol for web communication.View in glossary codes. Standardized exit codes (raps --help exit-codes) help fail fast in pipelines.

Batch upload resume (v4.5)

• State file location — batch upload state is saved in ~/.config/raps/batch-state.json (Linux/macOS) or %APPDATA%\raps\batch-state.json (Windows).
• Stale state — if --resume fails with “no matching state”, delete the state file manually and start fresh.
• Partial failures — when some files fail in a batch, state is saved automatically. Re-run with --resume to retry only failed files.
• Different bucket — resume only works for the same bucket and file set. Changing the target bucket requires a fresh upload.

Getting help

If issues persist, open a GitHub issue with your OS, RAPS version, and a minimal command that reproduces the problem. Sanitizing secrets before sharing logs keeps credentials safe.