/datadog-app

Troubleshooting

Use this when the user is diagnosing auth, upload, Node, site, or backend function failures.

Authentication Errors

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.

• For the default OAuth flow, rerun the command and complete the browser authorization prompt.
• Confirm the Datadog site configured in vite.config.ts matches the site used for OAuth.
• If the cached OAuth token is invalid or belongs to the wrong site, rerun the command and complete authorization again.
• If secure token storage is unavailable, install the optional keyring package requested by the warning, such as @napi-rs/keyring, or expect to reauthorize more often.
• For key-based auth, verify both 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.

Upload Fails With 403 "you do not have access to this app"

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:

1. Actions API Access — required for backend function execution during local dev.
2. Apps (or App Builder) — required for uploading and publishing app assets.

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.

Build Succeeds But Nothing Uploads

• When the intent is to upload, use npm run upload; do not rely on npm run build as the upload path.
• Confirm dryRun in vite.config.ts is not set to true.
• Check whether the upload output printed a Datadog app URL.
• Confirm DD_APPS_UPLOAD_ASSETS is enabled by the upload path.

Build Fails With Missing Credentials

• Current scaffold versions may make npm run build exercise Datadog upload behavior.
• Complete the OAuth browser flow before running build commands that touch Datadog.
• If using key-based auth, ensure both DD_API_KEY and DD_APP_KEY are set.
• For credential-free validation, prefer npm run typecheck when available.

Lint Fails Before Checking Code

• Some scaffold versions install ESLint 9 while generating legacy .eslintrc.cjs.
• If lint fails with an ESLint config-file error before checking source code, do not treat it as an app logic failure.
• Run npm run typecheck and build/upload validation, and report the scaffold lint mismatch to the Datadog Apps maintainers.

Node Or Scaffolding Errors

• The generated app guidance expects Node.js 20.19+ on the Node 20 release line, or Node.js 22.12+ on the Node 22 release line.
• If errors persist on a supported version, use a current Node 22 release.
• Use Volta, nvm, fnm, or the Node installer to switch versions.

Datadog Site Mismatch

• Inspect vite.config.ts for the configured Datadog site.
• If using OAuth, complete authorization against the same site.
• Ensure CI uses the same site configuration as local development.

Backend Function Issues

• Confirm backend files match *.backend.ts or *.backend.js.
• For local development, run npm run dev and complete OAuth authorization when prompted.
• If using key-based auth, confirm both DD_API_KEY and DD_APP_KEY are set and the application key has Actions API Access.
• Prefer @datadog/action-catalog typed actions when available.
• Check frontend imports reference the backend module path exactly.

Browser Debugging

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 --headed

Adapt the command to the app's configured test scripts when they exist.

Getting Help

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 or visit the Datadog developer documentation.