immich-app/immich · critical · Error

Invalid system config

Error message

Invalid system config: 
  - [${path}] ${issue.message}

What it means

buildConfig validates the raw system config against a Zod schema. If validation fails and a config file was the source, it throws with the list of zod issues (path + message). This is Immich's fail-fast guard against a corrupted or hand-edited immich config file.

Solutions

1. Fix each listed [path] issue in the config file per the message
2. Revert to a known-good config file or regenerate defaults from the admin UI (Administration > Settings)
3. Compare your config against the current version's SystemConfig schema for renamed/removed keys
4. Set the config via the web UI instead of manual file edits to guarantee schema validity

Example fix

// before (config file)
{ "ffmpeg": { "crf": "23", "transcode": "auto" } }
// after
{ "ffmpeg": { "crf": 23, "transcode": "auto" } }

import { z } from 'zod';
const parsed = SystemConfigSchema.safeParse(rawConfig);
if (!parsed.success) {
  for (const issue of parsed.error.issues) console.error(`[${issue.path.join('.')}] ${issue.message}`);
  throw new Error('Fix immich config before starting');
}

try {
  await startServer();
} catch (e) {
  if (/Invalid system config/.test(e.message)) {
    // log e.message fully: it enumerates each bad [path] and reason
    // restore defaults or fix listed keys, then restart
  }
}

When it happens

Trigger: Editing immich-config.json (or env-provided config) with unknown keys, wrong types, out-of-range values, or malformed JSON structure that fails the SystemConfig zod schema.

Common situations: Hand-editing the config after a version upgrade removed/renamed options; pasting config from an older Immich version; typos in enum values like transcode policies or ffmpeg settings.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid environment variables:
• Invalid system config:
• error instanceof Error ? error.message : error
• {error.message}
• Invalid environment variables: \n

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/5b6fe78b0adba08c. Report an issue: GitHub.

Appendix: source

Thrown at server/src/utils/config.ts:110

  const unknownKeys = cloneDeep(rawConfig);
  for (const property of getKeysDeep(defaults)) {
    unsetDeep(unknownKeys, property);
  }

  if (!isEmpty(unknownKeys)) {
    logger.warn(`Unknown keys found: ${JSON.stringify(unknownKeys, null, 2)}`);
  }

  // validate with Zod schema
  const result = AdminConfigDto.schema.safeParse(rawConfig);
  if (!result.success) {
    const messages = ['Invalid system config: '];
    for (const issue of result.error.issues) {
      const path = issue.path.join('.');
      messages.push(`  - [${path}] ${issue.message}`);
    }
    if (configFile) {
      throw new Error(messages.join('\n'));
    }
    logger.error('Validation error', messages);
  }

  const config = (result.success ? result.data : rawConfig) as SystemConfig;

  if (config.server.externalDomain.length > 0) {
    const domain = new URL(config.server.externalDomain);

    const externalDomain =
      domain.password && domain.username
        ? `${domain.protocol}//${domain.username}:${domain.password}@${domain.host}`
        : domain.origin;

    config.server.externalDomain = externalDomain;
  }

  if (!config.ffmpeg.acceptedVideoCodecs.includes(config.ffmpeg.targetVideoCodec)) {

View on GitHub (pinned to e55ac299a4)