{"record":{"id":"c41ebe0aa57e473e","repo":"immich-app/immich","slug":"cannot-update-configuration-while-immich-config-fi","errorCode":null,"errorMessage":"Cannot update configuration while IMMICH_CONFIG_FILE is in use","messagePattern":"Cannot update configuration while IMMICH_CONFIG_FILE is in use","errorType":"exception","errorClass":"BadRequestException","httpStatus":400,"severity":"error","filePath":"server/src/services/system-config.service.ts","lineNumber":62,"sourceCode":"\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\n    const newConfig = await this.updateConfig(dto);\n\n    await this.eventRepository.emit('ConfigUpdate', { newConfig, oldConfig });\n\n    return mapConfig(newConfig);\n  }\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/system-config.service.ts#L44-L80","documentation":"Thrown (as BadRequestException) by SystemConfigService.updateSystemConfig when IMMICH_CONFIG_FILE is set. With a config file in use, the database is no longer the source of truth, so writes via the admin API are refused to prevent divergence.","triggerScenarios":"PUT /system-config (or any admin UI save) while the server boots with IMMICH_CONFIG_FILE pointing at a JSON/YAML config.","commonSituations":"Operator migrated to file-based config but the admin UI is still used to tweak settings; CI deploys set IMMICH_CONFIG_FILE and a post-deploy script calls the config API.","solutions":["Edit the file referenced by IMMICH_CONFIG_FILE directly and restart the server.","If you want UI-managed config, unset IMMICH_CONFIG_FILE and restart (DB config then applies).","Confirm the env var is not set accidentally by a base image or compose override."],"exampleFix":"# before: file-based config blocks UI\nenvironment:\n  - IMMICH_CONFIG_FILE=/config/immich.json\n# after: UI-managed (remove the var, restart)\nenvironment: []","handlingStrategy":"validation","validationCode":"import { get } from 'node:process';\nfunction isConfigFileMode(): boolean { return Boolean(get('IMMICH_CONFIG_FILE')); }\nif (isConfigFileMode()) { /* edit the file, do not call PUT /system-config */ }","typeGuard":null,"tryCatchPattern":"try { await configApi.update(newConfig); }\ncatch (e) {\n  if (e instanceof BadRequestException && /IMMICH_CONFIG_FILE/.test(e.message)) {\n    // switch to file edits or unset the env var and restart\n  }\n}","preventionTips":["Pick one config strategy (DB or file) per deployment; do not mix.","When using IMMICH_CONFIG_FILE, version-control the file so changes are reviewed.","Document the chosen strategy in the runbook to prevent UI edits against file-managed servers."],"tags":["config","environment","validation","bad-request"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}