forge-debugger

What this skill does

# 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

```bash
forge --version
npm show @forge/cli version
```

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

```bash
npm install -g @forge/cli
```

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

## Step 3: Lint

```bash
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:

```bash
ls -la static/build/
```

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

```bash
cd static && npm run build && cd ..
```

Then redeploy:

```bash
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:

```bash
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

```bash
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:

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

Then redeploy and trigger the app again:

```bash
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:

```javascript
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
   ```
3. Note: production logs may be delayed up to 2 minutes after the event.
4. 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"