{"record":{"id":"7292d151eee41114","repo":"vxcontrol/pentagi","slug":"failed-to-load-document-w-7292d1","errorCode":null,"errorMessage":"failed to load document: %w","messagePattern":"failed to load document: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/tools/guide.go","lineNumber":283,"sourceCode":"\t\t\tmetadata[\"subtask_id\"] = *g.subtaskID\n\t\t}\n\n\t\tvar (\n\t\t\tdocs []schema.Document\n\t\t\tids  []string\n\t\t\terr  error\n\t\t)\n\n\t\tif len(anonymizedGuide) <= g.maxEmbeddingBytes || g.embedder == nil {\n\t\t\t// Fast path: document fits within the embedding limit.\n\t\t\tdocs, err = documentloaders.NewText(strings.NewReader(anonymizedGuide)).Load(ctx)\n\t\t\tif err != nil {\n\t\t\t\tobservation.Event(append(opts,\n\t\t\t\t\tlangfuse.WithEventStatus(err.Error()),\n\t\t\t\t\tlangfuse.WithEventLevel(langfuse.ObservationLevelError),\n\t\t\t\t)...)\n\t\t\t\tlogger.WithError(err).Error(\"failed to load document\")\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to load document: %w\", err)\n\t\t\t}\n\t\t\tfor i := range docs {\n\t\t\t\tif docs[i].Metadata == nil {\n\t\t\t\t\tdocs[i].Metadata = map[string]any{}\n\t\t\t\t}\n\t\t\t\tmaps.Copy(docs[i].Metadata, metadata)\n\t\t\t\tdocs[i].Metadata[\"part_size\"] = len(docs[i].PageContent)\n\t\t\t}\n\t\t\tids, err = g.store.AddDocuments(ctx, docs)\n\t\t\teventMetadata[\"ids\"] = ids\n\t\t\tif err != nil {\n\t\t\t\tobservation.Event(append(opts,\n\t\t\t\t\tlangfuse.WithEventStatus(err.Error()),\n\t\t\t\t\tlangfuse.WithEventLevel(langfuse.ObservationLevelError),\n\t\t\t\t)...)\n\t\t\t\tlogger.WithError(err).Error(\"failed to store guide\")\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to store guide: %w\", err)\n\t\t\t}","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/tools/guide.go#L265-L301","documentation":"Failed to load the anonymized guide document into the pgvector store via langchaingo's documentloader/add-documents path. The embedder call or the underlying database insert during AddDocuments returned an error.","triggerScenarios":"Calling the store_guide tool when the embeddings provider is unreachable/misconfigured, the pgvector extension/table is missing, or the DB connection is down during AddDocuments.","commonSituations":"OPENAI/other embeddings API key invalid or quota exhausted; PostgreSQL without the pgvector extension or with an old schema; DB max connections exhausted; network egress blocked from the container to the embeddings API.","solutions":["Read the wrapped error (%w): if it's an embeddings API error, fix the provider key/URL/quota.","If it's a database error, verify pgvector is installed and migrations ran (goose) in the backend DB.","Test embeddings connectivity (cmd/etester helper binary).","Check network/DNS from the Docker container to the embeddings endpoint.","Verify PostgreSQL connectivity and connection-pool limits."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// before calling store_guide, verify dependencies\nif embedder == nil { return errors.New(\"embedder not configured\") }\nif err := db.PingContext(ctx); err != nil { return fmt.Errorf(\"db unreachable: %w\", err) }","typeGuard":"func storeReady(g *guide) bool { return g.store != nil && g.embedder != nil && g.db != nil }","tryCatchPattern":"out, err := tool.Handle(ctx, \"store_guide\", args)\nif err != nil && strings.Contains(err.Error(), \"failed to load document\") {\n    if retriable(err) { // network/timeout/quota classes\n        time.Sleep(backoff)\n        return retry()\n    }\n    return fmt.Errorf(\"guide storage failed permanently: %w\", err)\n}","preventionTips":["Monitor embeddings API quota and key validity","Ensure pgvector extension and migrations are applied at deploy time","Set generous but bounded timeouts on embedder calls","Add health checks for DB and embedder before starting flows"],"tags":["database","pgvector","embeddings","network"],"backgroundTag":"vector-store-write-failed","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}