{"record":{"id":"af873464b9dcd01c","repo":"crewAIInc/crewAI","slug":"failed-to-load-data-from-postgresql-e","errorCode":null,"errorMessage":"Failed to load data from PostgreSQL: {e}","messagePattern":"Failed to load data from PostgreSQL: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/rag/loaders/postgres_loader.py","lineNumber":101,"sourceCode":"                    if len(content) > 100000:\n                        content = content[:100000] + \"\\n\\n[Content truncated...]\"\n\n                    return LoaderResult(\n                        content=content,\n                        metadata={\n                            \"source\": query,\n                            \"database\": connection_params[\"database\"],\n                            \"row_count\": len(rows),\n                            \"columns\": columns,\n                        },\n                        doc_id=self.generate_doc_id(source_ref=query, content=content),\n                    )\n            finally:\n                connection.close()\n        except Error as e:\n            raise ValueError(f\"PostgreSQL database error: {e}\") from e\n        except Exception as e:\n            raise ValueError(f\"Failed to load data from PostgreSQL: {e}\") from e\n","sourceCodeStart":83,"sourceCodeEnd":102,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/rag/loaders/postgres_loader.py#L83-L102","documentation":"The catch-all ValueError from PGFileLoader for any non-database exception during loading — most often connection failures raised before or during psycopg connect(): unknown hostname, refused connection, authentication failure, or missing psycopg driver. It wraps the original exception, so __cause__ carries the real reason.","triggerScenarios":"Network-level failures: host unreachable, wrong port, postgres not running, TLS requirement mismatch, or psycopg.OperationalError on bad credentials that is not an instance of the caught Error class path. Also triggered if the psycopg package itself is missing or incompatible.","commonSituations":"Connecting from a container to a DB on 'localhost' when the DB runs on the host (need host.docker.internal); DB behind a VPN not connected; password with special characters not URL-encoded in the URI; server requires SSL (sslmode=require) which the bare URI omits.","solutions":["Inspect the wrapped exception: except ValueError as e: print(e.__cause__) to get the underlying connection error.","Verify connectivity out-of-band: psql 'postgresql://user:pass@host:5432/db' -c 'select 1' from the same machine/container.","URL-encode special characters in the password (use urllib.parse.quote) or avoid them in the URI.","If the server requires TLS, append ?sslmode=require to the URI.","From Docker, replace localhost with the service name or host.docker.internal as appropriate."],"exampleFix":"# before\ndb_uri = \"postgresql://user:p@ssw0rd@host:5432/db\"  # '@' in password breaks parsing\n\n# after\nfrom urllib.parse import quote\ndb_uri = f\"postgresql://user:{quote('p@ssw0rd')}@host:5432/db\"","handlingStrategy":"retry","validationCode":"import psycopg\n\ndef can_connect(db_uri: str) -> bool:\n    try:\n        with psycopg.connect(db_uri, connect_timeout=5):\n            return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        result = pg_loader.load(src, metadata=md)\n        break\n    except ValueError as e:\n        if \"Failed to load\" in str(e) and is_transient(e.__cause__):\n            backoff(attempt)\n            continue\n        raise","preventionTips":["URL-encode passwords: urllib.parse.quote(password, safe='').","Add sslmode=require when the server enforces TLS.","Use a pre-flight connectivity check in orchestration before batch loads.","Log e.__cause__ always — the outer message hides the real network reason."],"tags":["postgres","database","network","connection"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}