{"record":{"id":"67d1006c2785faee","repo":"crewAIInc/crewAI","slug":"cannot-convert-type-value-name-to-file-sour","errorCode":null,"errorMessage":"Cannot convert {type(value).__name__} to file source","messagePattern":"Cannot convert (.+?) to file source","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/crewai-files/src/crewai_files/core/sources.py","lineNumber":578,"sourceCode":"\n\ndef _normalize_source(value: Any) -> FileSource:\n    \"\"\"Convert raw input to appropriate source type.\"\"\"\n    if isinstance(value, (FilePath, FileBytes, FileStream, AsyncFileStream, FileUrl)):\n        return value\n    if isinstance(value, str):\n        if value.startswith((\"http://\", \"https://\")):\n            return FileUrl(url=value)\n        return FilePath(path=Path(value))\n    if isinstance(value, Path):\n        return FilePath(path=value)\n    if isinstance(value, bytes):\n        return FileBytes(data=value)\n    if isinstance(value, AsyncReadable):\n        return AsyncFileStream(stream=value)\n    if hasattr(value, \"read\") and hasattr(value, \"seek\"):\n        return FileStream(stream=value)\n    raise ValueError(f\"Cannot convert {type(value).__name__} to file source\")\n\n\nRawFileInput = str | Path | bytes\nFileSourceInput = Annotated[\n    RawFileInput | FileSource, BeforeValidator(_normalize_source)\n]\n","sourceCodeStart":560,"sourceCodeEnd":585,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-files/src/crewai_files/core/sources.py#L560-L585","documentation":"Raised by the _normalize_source BeforeValidator in sources.py: the value's type matches none of the supported coercions — str (http(s) -> FileUrl, else FilePath), Path -> FilePath, bytes -> FileBytes, AsyncReadable instance -> AsyncFileStream, or an object with read+seek -> FileStream. Any other type (int, dict, list, sync generator, arbitrary object) reaches the final raise.","triggerScenarios":"Passing an int, dict, or None where a file source is expected (model field typed FileSourceInput); a generator or iterator object; a text-mode-only wrapper without read+seek; passing FileUrl/FilePath before importing them so isinstance checks in this module miss a re-exported class.","commonSituations":"Dynamic payloads from APIs (JSON objects) fed straight into file-source fields; users assuming any iterable of bytes coerces; version skew where the FilePath class the caller imported comes from a different module identity than the one checked.","solutions":["Convert to a supported type first: bytes -> FileBytes, path str/Path -> FilePath, http(s) str -> FileUrl, binary file object -> FileStream.","For dicts/JSON payloads, serialize to bytes: json.dumps(d).encode() then FileBytes.","Ensure you import source classes from crewai_files.core.sources itself so isinstance coercion matches."],"exampleFix":"# before\nFile(payload={\"name\": \"x\", \"data\": \"...\"})  # dict not supported\n\n# after\nimport json\nFile(payload=FileBytes(data=json.dumps(payload).encode()))","handlingStrategy":"type-guard","validationCode":"from pathlib import Path\nfrom crewai_files.core.sources import AsyncReadable\n\ndef coercible(v) -> bool:\n    return isinstance(v, (str, Path, bytes, AsyncReadable)) or (hasattr(v, \"read\") and hasattr(v, \"seek\"))","typeGuard":"from pathlib import Path\nfrom crewai_files.core.sources import FileUrl, FilePath, FileBytes, AsyncFileStream\n\ndef to_source(v):\n    if isinstance(v, str):\n        return FileUrl(url=v) if v.startswith((\"http://\", \"https://\")) else FilePath(path=Path(v))\n    if isinstance(v, Path):\n        return FilePath(path=v)\n    if isinstance(v, bytes):\n        return FileBytes(data=v)\n    if hasattr(v, \"read\") and hasattr(v, \"seek\"):\n        return FileStream(stream=v)\n    raise TypeError(f\"unsupported source type {type(v).__name__}\")","tryCatchPattern":"try:\n    File(source=raw)\nexcept ValidationError as e:\n    if \"to file source\" in str(e):\n        File(source=FileBytes(data=bytes(raw)))  # only when raw is bytes-like","preventionTips":["Convert payloads to one of str/Path/bytes/file-object before touching the API.","For JSON payloads, json.dumps(...).encode() into FileBytes."],"tags":["pydantic","validation","file-sources","type-coercion"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}