{"record":{"id":"18c2a469a35c0a01","repo":"phalcon/cphalcon","slug":"configuration-file-filename-cannot-be-loaded-18c2a4","errorCode":null,"errorMessage":"Configuration file {fileName} cannot be loaded","messagePattern":"Configuration file (.+?) cannot be loaded","errorType":"exception","errorClass":"Phalcon\\Config\\Exceptions\\CannotLoadConfigFile","httpStatus":null,"severity":"error","filePath":"phalcon/Config/Adapter/Yaml.zep","lineNumber":84,"sourceCode":"    {\n        var yamlConfig;\n\n        if unlikely !this->phpExtensionLoaded(\"yaml\") {\n            throw new MissingYamlExtension();\n        }\n\n        if empty(callbacks) {\n            let yamlConfig = this->phpYamlParseFile(filePath);\n        } else {\n            let yamlConfig = this->phpYamlParseFile(filePath, 0, callbacks);\n        }\n\n        if unlikely yamlConfig === null {\n            let yamlConfig = [];\n        }\n\n        if unlikely yamlConfig === false {\n            throw new CannotLoadConfigFile(basename(filePath));\n        }\n\n        parent::__construct(yamlConfig);\n    }\n}\n","sourceCodeStart":66,"sourceCodeEnd":90,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Config/Adapter/Yaml.zep#L66-L90","documentation":"After yaml_parse_file(), a null result (empty document) is normalized to an empty array, but a false result — the file could not be read or parsed — throws CannotLoadConfigFile with the basename. So this error means an unreadable file or a YAML parse failure, not an empty one.","triggerScenarios":"new Yaml('app/config/app.yaml') where the file is missing/unreadable, or the document fails to parse (tabs for indentation, broken syntax after secret substitution).","commonSituations":"Deploying without the yaml file; templating tools (envsubst-style) leaving invalid YAML behind; tabs or encoding issues introduced by Windows editors.","solutions":["Check is_file()/is_readable() before constructing","Lint the YAML in CI (yaml_parse or a validator) so syntax errors surface at build time","Use absolute paths built from __DIR__"],"exampleFix":"// before\n$config = new \\Phalcon\\Config\\Adapter\\Yaml('config/app.yaml');\n\n// after\n$path = dirname(__DIR__) . '/config/app.yaml';\nif (!is_readable($path)) {\n    throw new RuntimeException('Missing config file: ' . $path);\n}\n$config = new \\Phalcon\\Config\\Adapter\\Yaml($path);","handlingStrategy":"validation","validationCode":"$path = dirname(__DIR__) . '/config/app.yaml';\nif (!is_readable($path)) {\n    throw new RuntimeException('Config file missing or unreadable: ' . $path);\n}\n$config = new \\Phalcon\\Config\\Adapter\\Yaml($path);","typeGuard":null,"tryCatchPattern":"try {\n    $config = new \\Phalcon\\Config\\Adapter\\Yaml($path);\n} catch (\\Phalcon\\Config\\Adapter\\Yaml\\Exception\\CannotLoadConfigFile $e) {\n    // yaml_parse_file() returned false: unreadable file or parse error\n    throw new RuntimeException('Failed to load yaml config: ' . $path, 0, $e);\n}","preventionTips":["Check is_readable() before parsing; null (empty document) is fine, false is not","Lint YAML files in CI so syntax errors surface before deploy","Beware templated yaml: verify substitutions still leave valid YAML"],"tags":["phalcon","config","yaml","file-path","configuration"],"backgroundTag":"config-file-load-failed","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}