Setting the file. One moment.
Subchapter 23.7
references/troubleshooting.mdMarkdown5 KBView on GitHub
Use this when the user is diagnosing auth, upload, Node, site, or backend function failures.
Symptoms include 401s, Missing authentication token, backend function call failures, OAuth browser flow failures, cached token failures, or the Vite plugin logging Auth credentials not configured.
vite.config.ts matches the site used for OAuth.@napi-rs/keyring, or expect to reauthorize more often.DD_API_KEY and DD_APP_KEY are set. The application key needs Actions API Access for backend function execution and Apps for uploading.Optional key-based .env.local not being picked up: The generated config should read local env files before deciding whether to use API/application keys. If an older app reads credentials via process.env at config evaluation time, switch to Vite’s loadEnv:
import { defineConfig, loadEnv } from 'vite';
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), '');
return {
plugins: [
datadogVitePlugin({
auth: {
apiKey: env.DD_API_KEY,
appKey: env.DD_APP_KEY,
},
}),
],
};
});After updating vite.config.ts, restart the dev server. Credentials will be read from .env.local without shell exports, and OAuth remains the default when either key is absent.
The build and source map upload succeed but asset upload to App Builder fails with HTTP 403 Forbidden: you do not have access to this app.
For key-based auth, this is usually an application key permissions issue. The app key needs two scopes enabled:
Fix: go to https://app.datadoghq.com/organization-settings/application-keys, find your key, and confirm both scopes are enabled. If the Apps scope is missing, create a new key with both scopes.
After updating the key, re-run npm run upload. For OAuth, confirm the authorized user has access to upload the app.
npm run upload; do not rely on npm run build as the upload path.dryRun in vite.config.ts is not set to true.DD_APPS_UPLOAD_ASSETS is enabled by the upload path.npm run build exercise Datadog upload behavior.DD_API_KEY and DD_APP_KEY are set.npm run typecheck when available..eslintrc.cjs.npm run typecheck and build/upload validation, and report the scaffold lint mismatch to the Datadog Apps maintainers.vite.config.ts for the configured Datadog site.*.backend.ts or *.backend.js.npm run dev and complete OAuth authorization when prompted.DD_API_KEY and DD_APP_KEY are set and the application key has Actions API Access.@datadog/action-catalog typed actions when available.If Playwright is available, headed mode can be useful for troubleshooting local app behavior because it shows the browser session while preserving automation and console/network inspection:
npx playwright test --headedAdapt the command to the app’s configured test scripts when they exist.
If the user is stuck or has additional Datadog Apps questions, direct them to open an issue at https://github.com/DataDog/datadog-apps-claude-plugin/issues (opens in a new tab) or visit the Datadog developer documentation (opens in a new tab).