GitHub App mode misconfigured: GITHUB_APP_ID and WEBHOOK_SEC

Error message

GitHub App mode misconfigured: GITHUB_APP_ID and WEBHOOK_SECRET required

What it means

In GitHub App mode, startServer requires both GITHUB_APP_ID and WEBHOOK_SECRET to construct the GitHubAdapter; if either is missing at this point it throws a descriptive Error instead of building a partially configured adapter. Normally the mode selector (`hasGitHubApp`/selectGitHubAuthMode) guarantees both are present, so this is a fail-fast invariant check guarding the locals used below it.

Source

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

      throw new Error(ghAuthMode.message);
    }
    const hasGitHub = ghAuthMode.kind !== 'none';
    const hasGitea = Boolean(
      process.env.GITEA_URL && process.env.GITEA_TOKEN && process.env.GITEA_WEBHOOK_SECRET
    );
    const hasGitLab = Boolean(process.env.GITLAB_TOKEN && process.env.GITLAB_WEBHOOK_SECRET);

    if (!hasTelegram && !hasDiscord && !hasGitHub && !hasGitea && !hasGitLab) {
      getLog().warn('no_platform_adapters_configured');
    }

    if (ghAuthMode.kind === 'app') {
      // Locals avoid `!` non-null assertions: hasGitHubApp already guarantees
      // GITHUB_APP_ID and WEBHOOK_SECRET are set, but the linter can't infer that.
      const appId = process.env.GITHUB_APP_ID;
      const webhookSecret = process.env.WEBHOOK_SECRET;
      if (!appId || !webhookSecret) {
        throw new Error('GitHub App mode misconfigured: GITHUB_APP_ID and WEBHOOK_SECRET required');
      }
      const privateKey = loadAppPrivateKey();
      // Fail fast on a malformed TOKEN_ENCRYPTION_KEY when per-user is enabled,
      // so we never store unencryptable tokens at runtime. If the key is absent,
      // per-user GitHub is simply disabled (App-for-bot-only remains valid).
      assertEncryptionKeyAtBoot();
      if (!isPerUserGitHubEnabled()) {
        getLog().warn(
          'github_app.per_user_disabled — set TOKEN_ENCRYPTION_KEY (and GITHUB_APP_CLIENT_ID) to enable per-user GitHub identity'
        );
      }
      const defaultInstallationId = process.env.GITHUB_APP_INSTALLATION_ID
        ? Number(process.env.GITHUB_APP_INSTALLATION_ID)
        : undefined;
      githubAppAuthProvider = createGitHubAppAuthProvider({
        appId,
        privateKey,
        slug: process.env.GITHUB_APP_SLUG ?? 'archon',

View on GitHub (pinned to 0773b97458)

Solutions

Set both GITHUB_APP_ID and WEBHOOK_SECRET in the server environment and restart.
Check for empty-string definitions in .env (`VAR=` counts as set-but-empty to some loaders but not to this check) and fill in real values.
If you don't intend App mode, remove the App variables so the selector picks PAT or none.
Re-run `archon setup` to regenerate a complete GitHub App configuration.

Example fix

# before
GITHUB_APP_ID=Iv1.xxxx
# WEBHOOK_SECRET missing
# after
GITHUB_APP_ID=Iv1.xxxx
WEBHOOK_SECRET=whsec_xxx

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Use `archon setup` to generate App-mode env vars so none are skipped.
Beware empty-string env entries (`VAR=`) — they fail this check.
Re-verify environment after credential rotation or container recreation.
Confirm WEBHOOK_SECRET matches the secret configured on the GitHub App webhook.

When it happens

Trigger: selectGitHubAuthMode() returned kind === 'app' but process.env.GITHUB_APP_ID or process.env.WEBHOOK_SECRET is empty/undefined when read inside the app branch — e.g. a variable set to an empty string, or mode inference triggered by other App-related env vars while the required ones are unset.

Common situations: GITHUB_APP_ID set but WEBHOOK_SECRET forgotten when wiring GitHub App webhooks; an env var defined as empty (`GITHUB_APP_ID=`) in .env; stale container environment after rotating credentials; docs followed partially during App-mode setup.

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/22a34ccc42144bda. Report an issue: GitHub.