{"record":{"id":"a3717d00eb2c28c3","repo":"immich-app/immich","slug":"logging-cannot-be-changed-while-the-environment-va","errorCode":null,"errorMessage":"Logging cannot be changed while the environment variable IMMICH_LOG_LEVEL is set.","messagePattern":"Logging cannot be changed while the environment variable IMMICH_LOG_LEVEL is set\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/src/services/system-config.service.ts","lineNumber":55,"sourceCode":"    const configLevel = logging.enabled ? logging.level : false;\n    const level = envLevel ?? configLevel;\n    this.logger.setLogLevel(level);\n    this.logger.log(`LogLevel=${level} ${envLevel ? '(set via IMMICH_LOG_LEVEL)' : '(set via system config)'}`);\n\n    this.machineLearningRepository.setup(machineLearning);\n  }\n\n  @OnEvent({ name: 'ConfigUpdate', server: true })\n  onConfigUpdate({ newConfig }: ArgOf<'ConfigUpdate'>) {\n    this.onConfigInit({ newConfig });\n    clearConfigCache();\n  }\n\n  @OnEvent({ name: 'ConfigValidate' })\n  onConfigValidate({ newConfig, oldConfig }: ArgOf<'ConfigValidate'>) {\n    const { logLevel } = this.configRepository.getEnv();\n    if (logLevel && !_.isEqual(toPlainObject(newConfig.logging), oldConfig.logging)) {\n      throw new Error('Logging cannot be changed while the environment variable IMMICH_LOG_LEVEL is set.');\n    }\n  }\n\n  async updateSystemConfig(dto: SystemConfigDto): Promise<SystemConfigDto> {\n    const { configFile } = this.configRepository.getEnv();\n    if (configFile) {\n      throw new BadRequestException('Cannot update configuration while IMMICH_CONFIG_FILE is in use');\n    }\n\n    const oldConfig = await this.getConfig({ withCache: false });\n\n    try {\n      await this.eventRepository.emit('ConfigValidate', { newConfig: toPlainObject(dto), oldConfig });\n    } catch (error) {\n      this.logger.warn(`Unable to save system config due to a validation error: ${error}`);\n      throw new BadRequestException(error instanceof Error ? error.message : error);\n    }\n","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/system-config.service.ts#L37-L73","documentation":"Thrown (plain Error) by SystemConfigService.onConfigValidate when the IMMICH_LOG_LEVEL environment variable is set AND an incoming config update changes the logging block relative to the current one. The env var is treated as authoritative, so log config edits via the admin UI are rejected to avoid contradictory state.","triggerScenarios":"PUT /system-config with a modified logging field while the server process has IMMICH_LOG_LEVEL exported. The ConfigValidate event handler throws before any persistence.","commonSituations":"Operator set IMMICH_LOG_LEVEL=verbose for debugging, then tries to change logging.level through the UI; docker-compose env block pins IMMICH_LOG_LEVEL.","solutions":["Unset IMMICH_LOG_LEVEL (remove from docker env / systemd EnvironmentFile) and restart, then change logging via UI.","Keep IMMICH_LOG_LEVEL and change the env value directly instead of the UI.","If you must edit via UI, submit a config whose logging block equals the current one (no diff) to pass the _.isEqual check."],"exampleFix":"# before (env pins log level)\nenvironment:\n  - IMMICH_LOG_LEVEL=verbose\n# after (let UI control logging)\nenvironment: []\n# then restart and edit logging in Admin Settings","handlingStrategy":"validation","validationCode":"import { get } from 'node:process';\nfunction canEditLoggingViaUI(): boolean {\n  return !get('IMMICH_LOG_LEVEL');\n}\nif (!canEditLoggingViaUI()) { /* change the env var, do not PUT logging via API */ }","typeGuard":null,"tryCatchPattern":"try { await configApi.update(newConfig); }\ncatch (e) {\n  if (e instanceof BadRequestException && /IMMICH_LOG_LEVEL/.test(e.message)) {\n    // unset the env var, restart, then retry the save\n  }\n}","preventionTips":["Treat IMMICH_LOG_LEVEL as a temporary debugging knob; unset it in steady state.","Document which settings are env-overridden so admins do not attempt UI edits.","Diff old vs new logging block before submit and skip it if env is set."],"tags":["config","logging","environment","validation"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}