immich-app/immich · error · Error

Logging cannot be changed while the environment variable…

Error message

Logging cannot be changed while the environment variable IMMICH_LOG_LEVEL is set.

What it means

When IMMICH_LOG_LEVEL is set via environment, it takes precedence over the admin UI logging settings. onConfigValidate throws if a config save would change logging settings, because the change would be silently ignored or cause conflicting behavior.

Solutions

Remove the IMMICH_LOG_LEVEL environment variable and restart, then change logging via the admin UI
Keep IMMICH_LOG_LEVEL set and leave the logging section of the admin config unchanged
Resubmit the config without modifying the logging section

Example fix

// before
environment:
  IMMICH_LOG_LEVEL: verbose
// admin UI changes logging level -> error
// after
environment: {}
// then change log level in the admin UI

Defensive patterns

Strategy: validation

Validate before calling

if (process.env.IMMICH_LOG_LEVEL) {
  assert.deepStrictEqual(toPlainObject(newConfig.logging), oldConfig.logging,
    'Logging section must stay unchanged while IMMICH_LOG_LEVEL is set');
}

Type guard

null

Try / catch

try {
  await saveAdminConfig(dto);
} catch (e) {
  if (e.status === 500 && e.message.includes('IMMICH_LOG_LEVEL')) {
    dto = { ...dto, logging: oldLoggingSection }; // retry without logging change
  }
}

Prevention

Manage logging via ONE source: env var or admin UI, not both
Remove IMMICH_LOG_LEVEL if the UI should control log level
Diff config payloads against old config before saving

When it happens

Trigger: IMMICH_LOG_LEVEL env var is set AND an admin submits a system config whose logging section differs from the old config (e.g. changing log level in the admin UI).

Common situations: Admin tries to change log level from the web UI while the docker-compose file pins IMMICH_LOG_LEVEL; mixed env-var + database config.

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

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

Appendix: source

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

    const configLevel = logging.enabled ? logging.level : false;
    const level = envLevel ?? configLevel;
    this.logger.setLogLevel(level);
    this.logger.log(`LogLevel=${level} ${envLevel ? '(set via IMMICH_LOG_LEVEL)' : '(set via system config)'}`);

    this.machineLearningRepository.setup(machineLearning);
  }

  @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);
    }

View on GitHub (pinned to e55ac299a4)