coleam00/Archon · error

GitLabAdapter requires a non-empty token

Error message

GitLabAdapter requires a non-empty token

What it means

The GitLabAdapter constructor validates its required credentials at instantiation time: an empty (or falsy) token cannot authenticate any GitLab API call, so the adapter fails fast instead of producing confusing 401s later. It performs the same check for webhookSecret immediately after.

Source

Thrown at packages/adapters/src/community/forge/gitlab/adapter.ts:71

type ConversationLocker = Pick<ConversationLockManager, 'acquireLock'>;

export class GitLabAdapter implements IPlatformAdapter {
  private readonly gitlabUrl: string;
  private readonly token: string;
  private readonly webhookSecret: string;
  private readonly allowedUsers: string[];
  private readonly botMention: string;
  private readonly lockManager: ConversationLocker;

  constructor(
    token: string,
    webhookSecret: string,
    lockManager: ConversationLocker,
    gitlabUrl?: string,
    botMention?: string
  ) {
    if (!token) {
      throw new Error('GitLabAdapter requires a non-empty token');
    }
    if (!webhookSecret) {
      throw new Error('GitLabAdapter requires a non-empty webhookSecret');
    }

    this.gitlabUrl = (gitlabUrl ?? 'https://gitlab.com').replace(/\/+$/, '');
    this.token = token;
    this.webhookSecret = webhookSecret;
    this.lockManager = lockManager;
    this.botMention = botMention ?? 'Archon';

    this.allowedUsers = parseAllowedUsers(process.env.GITLAB_ALLOWED_USERS);
    if (this.allowedUsers.length > 0) {
      getLog().info({ userCount: this.allowedUsers.length }, 'gitlab.whitelist_enabled');
    } else {
      getLog().info('gitlab.whitelist_disabled');
    }

View on GitHub (pinned to 0773b97458)

Solutions

1. Set the GitLab token env/config value before constructing the adapter (a personal access or project token with api scope).
2. Verify the variable is non-empty at startup: print its length, not its value (never log the secret).
3. Check the .env file is actually loaded in the deployment (env var restored by .env loading can mask deletion — pass '' explicitly to Bun children to suppress).
4. Fix the config loader so it fails on missing required credentials rather than defaulting to empty strings.

Example fix

// before
const adapter = new GitLabAdapter(process.env.GITLAB_TOKEN ?? "", secret, locker);

// after
const token = process.env.GITLAB_TOKEN;
if (!token) throw new Error("GITLAB_TOKEN is required");
const adapter = new GitLabAdapter(token, secret, locker);

const token = process.env.GITLAB_TOKEN;
if (typeof token !== 'string' || token.length === 0) {
  throw new Error('GITLAB_TOKEN must be set to a non-empty value before creating GitLabAdapter');
}

function hasGitLabToken(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}

let adapter: GitLabAdapter;
try {
  adapter = new GitLabAdapter(token, webhookSecret, locker);
} catch (err) {
  if (err instanceof Error && err.message.includes('non-empty token')) {
    throw new Error('Startup misconfiguration: GITLAB_TOKEN is missing or empty', { cause: err });
  }
  throw err;
}

When it happens

Trigger: new GitLabAdapter(...) called with token === '' , undefined, or null — typically from an unset GITLAB_TOKEN environment variable or an empty string in the config file.

Common situations: GITLAB_TOKEN missing from .env or the deployment's secret store; env var exported as empty string (GITLAB_TOKEN= with no value); config loading silently defaulting to ''; migrating from another adapter and forgetting the GitLab credentials.

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.

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