{"record":{"id":"cb010ac67428195b","repo":"microsoft/semantic-kernel","slug":"failed-to-read-agent-spec-file-e","errorCode":null,"errorMessage":"Failed to read agent spec file: {e}","messagePattern":"Failed to read agent spec file: (.+?)","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":869,"sourceCode":"            extras: Additional parameters to resolve placeholders in the YAML.\n            encoding: The encoding of the file (default is 'utf-8').\n            **kwargs: Additional parameters passed to the agent constructor if required.\n\n        Returns:\n            An instance of the requested agent.\n\n        Raises:\n            AgentInitializationException: If the file is unreadable or the agent type is unsupported.\n        \"\"\"\n        _preload_builtin_agents()\n\n        try:\n            if encoding is None:\n                encoding = \"utf-8\"\n            with open(file_path, encoding=encoding) as f:\n                yaml_str = f.read()\n        except Exception as e:\n            raise AgentInitializationException(f\"Failed to read agent spec file: {e}\") from e\n\n        return await AgentRegistry.create_from_yaml(\n            yaml_str,\n            kernel=kernel,\n            plugins=plugins,\n            settings=settings,\n            extras=extras,\n            **kwargs,\n        )\n\n\n# endregion\n\n\n# region DeclarativeSpecMixin\n\n_D = TypeVar(\"_D\", bound=\"DeclarativeSpecMixin\")\n","sourceCodeStart":851,"sourceCodeEnd":887,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L851-L887","documentation":"Thrown by AgentRegistry.create_from_file when opening/reading the YAML spec file raises any exception (the broad `except Exception as e` wraps the open/read). The original exception is chained via `from e`. After a successful read the content is forwarded to create_from_yaml, so this error is purely an I/O / path problem, not a YAML parse problem.","triggerScenarios":"Calling create_from_file with a path that does not exist, lacks read permissions, is a directory, or has an encoding mismatch with the declared/utf-8 default encoding.","commonSituations":"Relative path resolved against an unexpected working directory; file generated with a non-UTF-8 encoding while encoding=None defaults to utf-8; permissions locked down in a container; path passed as a Path object whose str form differs from expectation.","solutions":["Verify the file exists and is readable at the exact path passed (`Path(file_path).exists()` and `.is_file()`).","Pass an explicit `encoding=` matching the file (e.g. 'utf-8-sig' for a BOM file).","Use an absolute path or resolve relative to a known base directory.","Check the chained exception (`__cause__`) for the precise OS-level reason."],"exampleFix":"# before\nawait AgentRegistry.create_from_file('configs/agent.yaml')  # wrong cwd\n\n# after\nfrom pathlib import Path\nbase = Path(__file__).parent / 'configs' / 'agent.yaml'\nawait AgentRegistry.create_from_file(str(base), encoding='utf-8')","handlingStrategy":"validation","validationCode":"from pathlib import Path\np = Path(file_path)\nassert p.is_file(), f'{file_path} is not a readable file'\nassert os.access(p, os.R_OK), f'{file_path} is not readable'","typeGuard":"from pathlib import Path\ndef is_readable_spec_file(path: str) -> bool:\n    p = Path(path)\n    return p.is_file() and os.access(p, os.R_OK)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    agent = await AgentRegistry.create_from_file(file_path, kernel=kernel)\nexcept AgentInitializationException as e:\n    cause = e.__cause__\n    logger.error('Could not read %s: %r', file_path, cause)\n    raise","preventionTips":["Use absolute paths resolved from a known base.","Pass an explicit encoding matching the file.","Check existence and read permission before the call."],"tags":["io","filesystem","encoding","declarative-spec","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}