mastra-ai/mastra · error

GithubIntegration: missing required config field(s): ${missi

Error message

GithubIntegration: missing required config field(s): ${missing.join(', ')}. Provide the full GitHub App credentials (appId, privateKey, clientId, clientSecret, slug) or omit the integration to disable GitHub-backed repositories.

What it means

The GithubIntegration constructor validates that all REQUIRED_FIELDS (appId, privateKey, clientId, clientSecret, slug) are present in the config. If any are missing or empty it throws immediately, instructing you to either supply the full GitHub App credentials or omit the integration entirely to disable GitHub-backed repositories.

Source

Thrown at mastracode/factory/src/integrations/github/integration.ts:350

   * The OAuth/install flow round-trips a signed `state` through GitHub, so a
   * multi-replica deploy needs a deployment-stable state secret.
   */
  readonly requiresStableStateSigner = true;

  readonly #appId: string;
  readonly #privateKey: string;
  readonly #clientId: string;
  readonly #clientSecret: string;
  readonly #slug: string;
  readonly #webhookSecret: string | undefined;
  readonly #authorizedBots: readonly string[];
  #storage: IntegrationContext['storage'] | undefined;
  #sourceControlStorage: IntegrationContext['storage']['sourceControl'] | undefined;

  constructor(config: GithubIntegrationConfig) {
    const missing = REQUIRED_FIELDS.filter(field => !config[field]);
    if (missing.length > 0) {
      throw new Error(
        `GithubIntegration: missing required config field(s): ${missing.join(', ')}. ` +
          `Provide the full GitHub App credentials (appId, privateKey, clientId, clientSecret, slug) ` +
          `or omit the integration to disable GitHub-backed repositories.`,
      );
    }
    this.#appId = config.appId;
    this.#privateKey = normalizePrivateKey(config.privateKey);
    this.#clientId = config.clientId;
    this.#clientSecret = config.clientSecret;
    this.#slug = config.slug;
    this.#webhookSecret = config.webhookSecret || undefined;
    this.#authorizedBots = (config.authorizedBots ?? []).map(bot => bot.trim()).filter(Boolean);
  }

  /** App slug — the URL name used to build the install URL. */
  get slug(): string {
    return this.#slug;
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide all five fields (appId, privateKey, clientId, clientSecret, slug) in the config object before constructing the integration
2. Check the missing field names listed in the message and fix the corresponding env vars/secret lookups
3. If GitHub-backed repositories are not needed, remove the integration from the factory config entirely so it is disabled rather than half-configured

Example fix

// before
new GithubIntegration({ appId: process.env.GITHUB_APP_ID }); // privateKey, clientId, clientSecret, slug missing
// after
new GithubIntegration({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  slug: process.env.GITHUB_APP_SLUG!,
});

const REQUIRED = ['appId', 'privateKey', 'clientId', 'clientSecret', 'slug'] as const;
const missing = REQUIRED.filter(f => !config[f]);
if (missing.length) throw new Error(`GitHub App config incomplete: ${missing.join(', ')}`);

function isGithubConfig(c: Partial<GithubIntegrationConfig>): c is GithubIntegrationConfig {
  return Boolean(c.appId && c.privateKey && c.clientId && c.clientSecret && c.slug);
}

try {
  const gh = new GithubIntegration(config);
} catch (e) {
  if (e.message.startsWith('GithubIntegration: missing required config field(s)')) {
    // surface which fields are missing; or omit the integration to disable it
  } else throw e;
}

When it happens

Trigger: Constructing new GithubIntegration(config) with any of appId, privateKey, clientId, clientSecret, or slug undefined, null, or an empty string — typically from incomplete environment variables or partially loaded secrets.

Common situations: Missing env vars in CI/deployment (GITHUB_APP_ID etc. not set); secrets manager returned only some fields; PEM private key failed to load (empty string); enabling the integration in one environment but not configuring all credentials.

Related errors

• Google client ID is required. Provide it in the options or s
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio
• Supabase URL and anon key are required, please provide them
• WorkOS API key and client ID are required. Provide them in t

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/5293b3f27ea8a050. Report an issue: GitHub.