GitHub PAT mode misconfigured: GITHUB_TOKEN and WEBHOOK_SECR

Error message

GitHub PAT mode misconfigured: GITHUB_TOKEN and WEBHOOK_SECRET required

What it means

In GitHub PAT mode, startServer requires both GITHUB_TOKEN and WEBHOOK_SECRET before constructing and starting the GitHubAdapter; if either is missing it throws. As with App mode, the mode selector should have guaranteed the token, so this guards against empty values and ensures webhook signature verification is always configured in PAT mode.

Source

Thrown at packages/server/src/index.ts:478

      // Per-user comment attribution: when enabled, let the adapter author PR/
      // issue comments under the originating user's GitHub identity. Resolver
      // returns undefined for unconnected users → bot identity fallback.
      const getUserToken = isPerUserGitHubEnabled()
        ? async (userId: string): Promise<string | undefined> =>
            (await getDecryptedAccessToken(userId)) ?? undefined
        : undefined;
      github = new GitHubAdapter(auth, webhookSecret, lockManager, botMention, { getUserToken });
      await github.start();
      activePlatforms.push('GitHub (App)');
      getLog().info(
        { slug: githubAppAuthProvider.slug, defaultInstallationId },
        'github.adapter_mode_app'
      );
    } else if (ghAuthMode.kind === 'pat') {
      const patToken = process.env.GITHUB_TOKEN;
      const webhookSecret = process.env.WEBHOOK_SECRET;
      if (!patToken || !webhookSecret) {
        throw new Error('GitHub PAT mode misconfigured: GITHUB_TOKEN and WEBHOOK_SECRET required');
      }
      const botMention =
        process.env.GITHUB_BOT_MENTION || process.env.BOT_DISPLAY_NAME || config.botName;
      const auth: GitHubAuth = { kind: 'pat', token: patToken };
      github = new GitHubAdapter(auth, webhookSecret, lockManager, botMention);
      await github.start();
      activePlatforms.push('GitHub');
      getLog().info('github.adapter_mode_pat');
    } else {
      getLog().info('github_adapter_skipped');
    }

    // Initialize Gitea adapter (conditional)
    if (process.env.GITEA_URL && process.env.GITEA_TOKEN && process.env.GITEA_WEBHOOK_SECRET) {
      const giteaBotMention =
        process.env.GITEA_BOT_MENTION || process.env.BOT_DISPLAY_NAME || config.botName;
      gitea = new GiteaAdapter(
        process.env.GITEA_URL,

View on GitHub (pinned to 0773b97458)

Solutions

Set GITHUB_TOKEN (a valid PAT with required scopes) and WEBHOOK_SECRET (matching the secret configured on the GitHub repo/app webhook) and restart.
Confirm the same WEBHOOK_SECRET value is configured on the GitHub webhook side, or signature verification will fail later.
Check .env and the process environment for empty definitions (`GITHUB_TOKEN=`) and correct them.
If App mode was intended instead, remove GITHUB_TOKEN and provide the App-mode variables.

Example fix

# before
GITHUB_TOKEN=ghp_xxx
# after: add the webhook secret
GITHUB_TOKEN=ghp_xxx
WEBHOOK_SECRET=whsec_xxx

Defensive patterns

Strategy: validation

Validate before calling

for (const k of ['GITHUB_TOKEN', 'WEBHOOK_SECRET']) {
  const v = process.env[k];
  if (!v || v.trim() === '') throw new Error(`${k} must be set for GitHub PAT mode`);
}

Try / catch

try {
  await startServer(config);
} catch (e) {
  if (/GitHub PAT mode misconfigured/i.test(e?.message ?? '')) {
    logFatal('Set GITHUB_TOKEN and WEBHOOK_SECRET (PAT mode) in the server environment.');
    process.exit(1);
  }
  throw e;
}

Prevention

Set WEBHOOK_SECRET alongside GITHUB_TOKEN from day one — the token alone is insufficient.
Keep the same secret value configured on the GitHub repo webhook.
Validate env completeness in CI or a pre-start script.
Watch for empty-string definitions when templating .env files.

When it happens

Trigger: selectGitHubAuthMode() returned kind === 'pat' but process.env.GITHUB_TOKEN or process.env.WEBHOOK_SECRET is empty/undefined inside the pat branch of startServer.

Common situations: GITHUB_TOKEN set but GITEA/GitLab-style secret names used instead of WEBHOOK_SECRET; token defined as empty after a failed sed/rotation; webhook secret dropped while porting a PAT setup between hosts; mixing up the repo webhook secret with the GitHub App webhook secret.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/b5cf591905747c0e. Report an issue: GitHub.