immich-app/immich · error · BadRequestException

Cannot update configuration while IMMICH_CONFIG_FILE is in…

Error message

Cannot update configuration while IMMICH_CONFIG_FILE is in use

What it means

When IMMICH_CONFIG_FILE points at a config file, the runtime configuration is managed by that file and is read-only through the API. updateAdminConfig throws BadRequestException to prevent drift between the file and the stored database config.

Solutions

1. Remove the IMMICH_CONFIG_FILE environment variable and restart the server, then manage config via the UI/API
2. Edit the referenced config file directly instead of using the admin UI
3. Keep the admin UI read-only for config while file-based config is in use

Example fix

// before
environment:
  IMMICH_CONFIG_FILE: /config/immich.json
// admin UI save -> error
// after
environment: {}
// manage config via admin UI, or edit /config/immich.json directly

if (process.env.IMMICH_CONFIG_FILE) throw new Error('Runtime config is read-only: IMMICH_CONFIG_FILE is set');

null

try {
  await saveAdminConfig(dto);
} catch (e) {
  if (e.status === 400 && e.message.includes('IMMICH_CONFIG_FILE')) {
    // persist changes to the config file instead, or ask operator to unset the env var
  }
}

When it happens

Trigger: Any admin UI or API attempt to save system config while IMMICH_CONFIG_FILE env var is set in the server environment.

Common situations: Deployments pinned by a config file where an admin edits settings in the web UI; teams switching from file-based to DB-based config without removing the env var.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• error instanceof Error ? error.message : error
• {error.message}
• Logging cannot be changed while the environment variable…
• Asset does not have valid dimensions
• Asset not found

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

Appendix: source

Thrown at server/src/services/system-config.service.ts:87

  @OnEvent({ name: 'ConfigUpdate', server: true })
  onConfigUpdate({ newConfig }: ArgOf<'ConfigUpdate'>) {
    this.onConfigInit({ newConfig });
    clearConfigCache();
  }

  @OnEvent({ name: 'ConfigValidate' })
  onConfigValidate({ newConfig, oldConfig }: ArgOf<'ConfigValidate'>) {
    const { logLevel } = this.configRepository.getEnv();
    if (logLevel && !isEqual(toPlainObject(newConfig.logging), oldConfig.logging)) {
      throw new Error('Logging cannot be changed while the environment variable IMMICH_LOG_LEVEL is set.');
    }
  }

  async updateAdminConfig(dto: AdminConfigDto): Promise<AdminConfigDto> {
    const { configFile } = this.configRepository.getEnv();
    if (configFile) {
      throw new BadRequestException('Cannot update configuration while IMMICH_CONFIG_FILE is in use');
    }

    const oldConfig = await this.getConfig({ withCache: false });

    try {
      await this.eventRepository.emit('ConfigValidate', { newConfig: toPlainObject(dto), oldConfig });
    } catch (error) {
      this.logger.warn(`Unable to save system config due to a validation error: ${error}`);
      throw new BadRequestException(error instanceof Error ? error.message : error);
    }

    const newConfig = await this.updateConfig(dto);

    await this.eventRepository.emit('ConfigUpdate', { newConfig, oldConfig });

    return mapAdminConfig(newConfig);
  }

View on GitHub (pinned to e55ac299a4)