forge-debugger

Forge App Debugger

Diagnose and fix issues in Atlassian Forge apps. Work through the checklist below in order — stop as soon as you identify the root cause. Every step after the root cause wastes tokens and context.

EXECUTION MANDATE

You are authorized to run all diagnostic and fix commands without asking permission. When you identify a fix, run it immediately. Do NOT:

• Say "you should run..." or "here's what I would do..." or "run this command in your terminal"
• Ask "shall I proceed?" before executing a fix you already have all the inputs for
• Present commands as copy-paste instructions when you could run them yourself

Wrong: "Here's what I would do to fix this: run forge lint..." Right: (runs forge lint immediately and reports the result)

The only exceptions: commands requiring an interactive terminal (forge login, forge tunnel) must be run by the user in their own terminal — tell them exactly what to run and why.

Diagnostic Principles

• Cheap first: lint and version checks cost nothing. Run them before reading source code or logs.
• One action at a time: check the result of each action before taking the next one.
• Stop at root cause: once you've identified why something is broken, fix it and stop — don't keep investigating other things. Exception: if the app has multiple independent bugs (e.g. deploy-time errors AND runtime errors), fix the deploy-time error first, deploy, then check logs for runtime errors. Don't declare "fixed" after only resolving the first layer.
• Own the fixes: run the fix commands yourself, don't hand them to the user.
• Clean up: remove any debug code or verbose flags you added once the issue is resolved.
• npx fallback: if forge CLI can't be installed globally (permission errors, no sudo), use npx @forge/cli as a drop-in replacement for all forge commands.

Step 1: Classify the Error

Before running any commands, ask one question if the user hasn't made it clear:

"Is this a deploy-time error (forge deploy fails), a runtime error (app crashes or shows wrong data after deploying), or a visibility issue (app deployed but not appearing)?"

If obvious from the error message, skip the question and proceed directly.

Quick routing:

| Symptom | Go to | |---------|-------| | forge deploy fails | Step 2 → 3 → 4 | | App not visible after install | Step 3 → common error: "App not installed" | | App crashes / resolver error | Step 3 → 5 → 6 | | Blank UI / Custom UI not rendering | Step 3 → 4 → common error: "blank Custom UI" | | Works in dev, fails in prod | Step 7 (Production) | | Permission denied / 403 | Common error: "Permission denied" | | 410 Gone / deprecated endpoint | Common error: "410 Gone" → API Migration section | | Handler path lint error | Common error: "cannot find associated file" → Handler Path Resolution section | | Resolver returns undefined, no errors | Common error: invoke name mismatch → Invoke Name vs Function Key section | | Multiple failures (deploy + runtime) | Fix deploy errors first, deploy, then check logs for runtime errors |

Step 2: Version Check

forge --version
npm show @forge/cli version

If the installed version is behind the latest major version, upgrade immediately:

npm install -g @forge/cli

Then retry the failing operation. Many bugs are fixed in newer CLI versions.

Step 3: Lint

forge lint

Fix every error before proceeding — lint errors cause deploy failures and silent runtime bugs. If lint passes cleanly, continue to the next step.

For any manifest-related error message (e.g. "invalid manifest", "unexpected key", "modules.jira:*" errors): run forge lint first before reading any source files. Lint will identify the exact line and field causing the problem — reading the file before linting is wasteful and usually less informative than the lint output.

Step 4: Custom UI Build Check

Only applies when the app has a static/ directory (Custom UI apps). Check if the frontend was built before the last deploy:

ls -la static/build/

If the build directory is missing or older than recent source changes, rebuild:

cd static && npm run build && cd ..

Then redeploy:

forge deploy -e development

This is one of the most common causes of blank UI panels.

Step 5: Deploy Status

Verify the app was actually deployed successfully:

forge deploy -e development --verbose

Watch for errors in the output. Note the deploy timestamp. If deploy fails, the error message usually identifies the problem directly — match it against the Common Error Patterns table below.

Step 6: Logs

forge logs -e development --limit 100

Read the logs carefully. Most runtime errors appear here.

If no logs are returned

The resolver may not have been triggered, or logging isn't set up. Add a debug log at the entry point of the resolver:

// Add at the top of your handler function:
console.error('[DEBUG] Handler called with:', JSON.stringify(payload));

Then redeploy and trigger the app again:

forge deploy -e development
forge logs -e development --limit 100

Remove the debug log after you've identified the issue.

If the error is in the frontend (UI rendering, blank screen)

Forge UI Kit errors surface in forge logs, not the browser console. For Custom UI, add error logging in the resolver that backs the UI:

try {
  const result = await api.asUser().requestJira(/* ... */);
  return result;
} catch (err) {
  console.error('[DEBUG] Resolver error:', err.message, err.stack);
  throw err;
}

Redeploy, trigger, and check logs.

Step 7: Production Issues

If the user reports an issue that only happens in production (or on a specific customer's site):

1. Ask: "Which Atlassian site is affected? (e.g. customername.atlassian.net)"
2. Check production logs:

``bash forge logs -e production --site <customer-site> --limit 100 ``

1. Note: production logs may be delayed up to 2 minutes after the event.
2. If the issue is permission-related, check whether scopes were upgraded after a new install — production installs require explicit --upgrade.

Common Error Patterns

Match the error against this table first. If you find a match, apply the fix directly without further investigation.

| Error / Symptom | Root Cause | Fix | |-----------------|-----------|-----| | "App is not installed on this site" | forge install wasn't run, or ran against wrong site | Ask for the Atlassian site URL if not already known, then run it yourself: forge install --non-interactive --site <url> --product <jira\|confluence> -e development | | Blank panel / Custom UI white screen | Frontend build not run before deploy | cd static && npm run build && cd .. && forge deploy -e development | | "Resolver not found" or resolver returns undefined | Function key in manifest.yml doesn't match resolver registration | Check manifest.yml function.key matches the key used in resolver.define('key', ...) | | 403 / "Permission denied" / "Unauthorized" | OAuth scope missing from manifest | Add scope to manifest.yml, then: forge deploy -e development && forge install --non-interactive --site <url> --upgrade | | forge deploy fails with "Invalid manifest" | YAML syntax error in manifest.yml | Run forge lint, fix indentation/syntax errors | | App deployed but module not visible | Wrong product in forge install, or tunnel not active | Verify --product flag matches app type; restart tunnel if using forge tunnel | | "forge: command not found" | CLI not installed | npm install -g @forge/cli | | ENOENT or missing files on deploy | npm install not run in app directory | cd <app-dir> && npm install && forge deploy -e development | | "Rate limit exceeded" | Too many API calls in resolver | Add exponential backoff; check for resolver being called in a loop | | "App tunnel disconnected" |