{"record":{"id":"73b58c34289f5379","repo":"sebastianbergmann/php-text-template","slug":"failed-to-load-template-s","errorCode":null,"errorMessage":"Failed to load template \"%s\"","messagePattern":"Failed to load template \"(.+?)\"","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Template.php","lineNumber":124,"sourceCode":"        if (is_file($file)) {\n            $template = file_get_contents($file);\n\n            if (is_string($template) && $template !== '') {\n                return $template;\n            }\n        }\n\n        $distFile = $file . '.dist';\n\n        if (is_file($distFile)) {\n            $template = file_get_contents($distFile);\n\n            if (is_string($template) && $template !== '') {\n                return $template;\n            }\n        }\n\n        throw new InvalidArgumentException(\n            sprintf(\n                'Failed to load template \"%s\"',\n                $file,\n            ),\n        );\n    }\n}\n","sourceCodeStart":106,"sourceCodeEnd":132,"githubUrl":"https://github.com/sebastianbergmann/php-text-template/blob/1e6083ad3a7992a7b5eb60856a078f9d5ce6f714/src/Template.php#L106-L132","documentation":"Template's constructor loads the template file immediately via loadTemplateFile(). The loader first tries the given path; if it is not a readable file (or reads as empty), it retries with a '.dist' suffix appended (e.g. config/config.dist). If neither file yields a non-empty string, an InvalidArgumentException naming the original path is thrown. Since the property is readonly, a failed construction cannot be retried on the same instance.","triggerScenarios":"new Template($file) where $file does not exist, the path is misspelled or relative to the wrong CWD, the file exists but is not readable (permissions), the file is empty (0 bytes), or neither $file nor $file.'.dist' exists/readable/non-empty.","commonSituations":"Publishing mistakes where the real config/template was never copied and the .dist fallback is also absent (typical PHPUnit/php-code-generator setups that expect you to copy the .dist); application deployed without its templates directory; wrong base path passed after a refactor; file exists but is empty because a build step failed; open_basedir or permission issues making is_file()/file_get_contents() fail.","solutions":["Check the exact path in the message: confirm the file exists (is_file / ls) and is readable by the PHP process user","If it is missing, copy the shipped .dist file to the expected path (e.g. cp config/config.dist config/config) or fix the path passed to the constructor","If the file exists but is empty, restore its contents — an empty file also triggers this error","Run from the correct working directory or pass absolute paths so relative template paths resolve as intended"],"exampleFix":"// before\n$template = new Template('config/config'); // file missing -> throws\n\n// after\n$file = __DIR__ . '/config/config';\nif (!is_file($file) && is_file($file . '.dist')) {\n    copy($file . '.dist', $file);\n}\nif (!is_file($file) || filesize($file) === 0) {\n    throw new RuntimeException('Template file missing or empty: ' . $file);\n}\n$template = new Template($file);","handlingStrategy":"validation","validationCode":"if (!is_file($file) || filesize($file) === 0) {\n    if (is_file($file . '.dist')) {\n        copy($file . '.dist', $file);\n    } else {\n        throw new RuntimeException('Template not found: ' . $file);\n    }\n}\n$template = new Template($file);","typeGuard":null,"tryCatchPattern":"try {\n    $template = new Template($templateFile);\n} catch (\\SebastianBergmann\\Template\\InvalidArgumentException $e) {\n    // surface a clear message about the missing/empty template path\n}","preventionTips":["Ship the .dist file and document that users must copy it to the real name before first run","Resolve template paths against __DIR__ or a configured base path, not the CWD","Check is_file() and non-empty size before constructing Template","Verify deploy scripts include the templates/config directory"],"tags":["php","filesystem","file-not-found","template"],"backgroundTag":"file-not-found","analyzedSha":"1e6083ad3a7992a7b5eb60856a078f9d5ce6f714","analyzedAt":"2026-09-14T11:21:17.064Z","contentChangedAt":"2026-09-14T11:21:17.064Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}