{"record":{"id":"0ee9e267c2da2064","repo":"toeverything/AFFiNE","slug":"invalid-config-for-module-module-with-key","errorCode":null,"errorMessage":"Invalid config for module [${module}] with key [${key}]\nValue: ${JSON.stringify(defaultValue)}\nError: ${issue.message}","messagePattern":"Invalid config for module \\[(.+?)\\] with key \\[(.+?)\\]\nValue: (.+?)\nError: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/backend/server/src/base/config/register.ts","lineNumber":370,"sourceCode":"\n  for (const [module, defs] of Object.entries(APP_CONFIG_DESCRIPTORS)) {\n    const modulizedConfig = {};\n\n    for (const [key, desc] of Object.entries(defs)) {\n      let defaultValue = desc.default;\n\n      if (desc.env) {\n        const [env, parser] = desc.env;\n        const envValue = envs[env];\n        if (envValue) {\n          defaultValue = parseEnvValue(envValue, parser);\n        }\n      }\n\n      const { success, error } = desc.validate(defaultValue);\n\n      if (!success) {\n        throw new Error(\n          error.issues\n            .map(issue => {\n              return `Invalid config for module [${module}] with key [${key}]\nValue: ${JSON.stringify(defaultValue)}\nError: ${issue.message}`;\n            })\n            .join('\\n')\n        );\n      }\n\n      set(modulizedConfig, key, defaultValue);\n    }\n\n    // @ts-expect-error all keys are known\n    config[module] = modulizedConfig;\n  }\n\n  CONFIG_JSON_PATHS.forEach(path => {","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/toeverything/AFFiNE/blob/26c515e050211269e911f7d9cfe162a26c83ed98/packages/backend/server/src/base/config/register.ts#L352-L388","documentation":"Thrown by getDefaultConfig() during server startup when a configuration value fails its Zod validation schema. The error message includes the module name, config key, the invalid value (JSON-serialized), and the specific Zod issue message. This is a fatal startup error — the server cannot boot with invalid configuration.","triggerScenarios":"Server boot when process.env or config JSON provides a value for a config key that fails desc.validate (a Zod safeParse). For example, an env var meant to be a URL that contains a non-URL string, or a numeric port that's actually a word. The error fires in the loop over APP_CONFIG_DESCRIPTORS.","commonSituations":"Typo in an environment variable value (e.g. PORT=abc instead of a number). JSON config override file with wrong types. Missing required config with an invalid default. Deploying with stale .env files from a previous version where the expected schema changed.","solutions":["Read the error message: it names the module, key, the bad value, and the Zod issue — fix the value to match the expected type/schema.","Check the corresponding env var or JSON config path for the failing key and correct the value.","Consult the config descriptor (APP_CONFIG_DESCRIPTORS) for the expected type and constraints of that key.","After fixing, restart the server to re-run config validation."],"exampleFix":"// before (.env)\nMAILER_HOST=\"not a url\"\n\n// The Zod validation for this key expects a valid hostname/URL.\n// after\nMAILER_HOST=\"smtp://smtp.example.com:587\"","handlingStrategy":"validation","validationCode":"// Before starting the server, validate config in a dry-run:\n// import { getDefaultConfig } from './config/register';\n// try { getDefaultConfig(); } catch (e) { console.error(e.message); process.exit(1); }\n//\n// Or validate individual env vars:\nfunction validateEnvVar(key: string, value: string | undefined, validator: (v: string) => boolean) {\n  if (value && !validator(value)) {\n    throw new Error(`Invalid value for ${key}: ${value}`);\n  }\n}\nvalidateEnvVar('AFFINE_SERVER_PORT', process.env.AFFINE_SERVER_PORT, v => /^\\d+$/.test(v));","typeGuard":null,"tryCatchPattern":"try {\n  const config = getDefaultConfig();\n  // start server with config\n} catch (e) {\n  console.error('Configuration validation failed:', e.message);\n  process.exit(1);\n}","preventionTips":["Review all config descriptors and their expected types before deployment.","Use a config validation step in CI/CD before deploying.","Keep .env.example updated with correct types and examples for every config key.","After version upgrades, diff the config descriptors to catch schema changes."],"tags":["affine-backend","config","startup","zod","validation","environment"],"backgroundTag":null,"analyzedSha":"26c515e050211269e911f7d9cfe162a26c83ed98","analyzedAt":"2026-08-12T13:15:16.447Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}