{"record":{"id":"fe50f58e66bf7649","repo":"phalcon/cphalcon","slug":"environment-variable-varname-is-not-defined","errorCode":null,"errorMessage":"Environment variable '{varname}' is not defined","messagePattern":"Environment variable '(.+?)' is not defined","errorType":"exception","errorClass":"Phalcon\\Container\\Exceptions\\EnvNotDefined","httpStatus":null,"severity":"error","filePath":"phalcon/Container/Resolver/Lazy/Env.zep","lineNumber":98,"sourceCode":"        }\n\n        return value;\n    }\n\n    /**\n     * Return the env value\n     *\n     * @return string\n     * @throws EnvNotDefined\n     */\n    protected function getEnv() -> string\n    {\n        var envs;\n\n        let envs = array_merge(_ENV, getenv());\n\n        if (!array_key_exists(this->varname, envs)) {\n            throw new EnvNotDefined(this->varname);\n        }\n\n        return envs[this->varname];\n    }\n}\n","sourceCodeStart":80,"sourceCodeEnd":104,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Container/Resolver/Lazy/Env.zep#L80-L104","documentation":"Lazy\\Env wraps an environment variable and reads it lazily when the service is built. getEnv() merges $_ENV and getenv() and throws EnvNotDefined if the variable appears in neither. Because resolution is deferred, the exception surfaces at container build time — often deep inside service construction — rather than where new Env() was written.","triggerScenarios":"set('db', ...) with a constructor arg of new Env('DB_HOST') while DB_HOST is not defined; the .env loader not run (or run after resolution); variable renamed (DBHOST vs DB_HOST); CLI/cron contexts where the variable was only set for the web SAPI; container secrets not exported in docker/k8s.","commonSituations":"Deployments where .env loading happens after container build; CI pipelines missing required variables; case mismatches between $_ENV and getenv() sources; local dev works (dotenv loaded) but production fails.","solutions":["Define the variable in the environment, or load your .env file before the container resolves any service using Env","Guard at boot: if (getenv('DB_HOST') === false && !isset($_ENV['DB_HOST'])) { fail fast with a clear message }","Check exact spelling and case, and export the variable in CLI/cron/unit-test contexts","Assert required variables early in bootstrap so the failure names the missing var, not a stack trace inside a factory"],"exampleFix":"// before\n$container->set('db', Connection::class)\n    ->setConstructorArgs([new Env('DB_HOST')]);\n// EnvNotDefined at first get('db') when DB_HOST is unset\n\n// after\n// bootstrap.php\n$required = ['DB_HOST'];\nforeach ($required as $var) {\n    if (getenv($var) === false && !isset($_ENV[$var])) {\n        throw new RuntimeException('Missing env var: ' . $var);\n    }\n}","handlingStrategy":"validation","validationCode":"function envDefined(string $name): bool\n{\n    return getenv($name) !== false || isset($_ENV[$name]);\n}\n\n// bootstrap assertion, fails fast before any service resolves\nforeach (['DB_HOST', 'DB_NAME'] as $var) {\n    if (!envDefined($var)) {\n        throw new RuntimeException('Missing required environment variable: ' . $var);\n    }\n}","typeGuard":null,"tryCatchPattern":"use Phalcon\\Container\\Resolver\\Lazy\\Env;\nuse Phalcon\\Container\\Exceptions\\EnvNotDefined;\n\ntry {\n    $value = (new Env('DB_HOST'))->resolve($container);\n} catch (EnvNotDefined $e) {\n    $value = 'localhost'; // explicit fallback with logging\n}","preventionTips":["Load .env before the container resolves anything; assert required vars at boot","Keep one canonical spelling per variable (case included) in code and infrastructure","Remember Env merges $_ENV and getenv() — export vars in CLI, cron, and CI contexts too"],"tags":["di-container","environment-variables","lazy-resolution","phalcon"],"backgroundTag":"missing-env-var","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}