{"record":{"id":"0a5504eb664e0c7b","repo":"n8n-io/n8n","slug":"supabase-query-failed-error-message","errorCode":null,"errorMessage":"Supabase query failed: ${error.message}","messagePattern":"Supabase query failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/vector-stores/supabase.ts","lineNumber":139,"sourceCode":"\t\t);\n\t\tif (error) throw new Error(`Supabase upsert failed: ${error.message}`);\n\t}\n\n\tasync query(\n\t\tvector: number[],\n\t\topts: { topK: number; filter?: VectorFilter },\n\t): Promise<VectorQueryResult[]> {\n\t\tconst client = await this.getClient();\n\t\tconst rpcCall = client.rpc<string, MatchDocumentsFn>(this.queryName, {\n\t\t\tquery_embedding: vector,\n\t\t});\n\t\tconst filtered =\n\t\t\topts.filter && opts.filter.conditions.length > 0\n\t\t\t\t? applySupabaseFilter(rpcCall, opts.filter)\n\t\t\t\t: rpcCall;\n\n\t\tconst { data, error } = await filtered.limit(opts.topK);\n\t\tif (error) throw new Error(`Supabase query failed: ${error.message}`);\n\n\t\treturn (data ?? []).map(toQueryResult);\n\t}\n\n\tasync delete({ ids }: { ids: string[] }): Promise<void> {\n\t\tif (ids.length === 0) return;\n\n\t\tconst client = await this.getClient();\n\t\tconst { error } = await client.from(this.tableName).delete().in('id', ids);\n\t\tif (error) throw new Error(`Supabase delete failed: ${error.message}`);\n\t}\n\n\tclose(): void {\n\t\tthis.client = undefined;\n\t}\n\n\tprivate async getClient(): Promise<SupabaseClient> {\n\t\tif (!this.client) {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/vector-stores/supabase.ts#L121-L157","documentation":"Thrown by SupabaseVectorStore.query when the PostgREST RPC call (to match_documents by default, or queryName) returns a non-null error. Common root causes exposed in the appended message: the RPC function does not exist, the vector dimension does not match the column's vector(n), wrong queryName, RLS blocking SELECT, or a connection/auth failure. Runtime/backend error, not local validation.","triggerScenarios":"Default RPC `match_documents` not defined in the database; queryName customized to a function that doesn't exist; embedding model changed to a different dimension than the table's vector(n) column; RLS denying select on the table; Supabase unreachable/auth expired; passing a vector of the wrong length.","commonSituations":"Switching embedding models without re-creating the vector column at the new dimension; forgetting to run the match_documents SQL from the store docs; custom queryName typo; RLS on the table blocking the query role.","solutions":["Read the appended message — it distinguishes 'function does not exist' from 'dimensions don't match' from RLS errors.","Create the RPC function exactly as in the store's JSDoc (parameter `query_embedding vector(n)`, returns id/content/metadata/similarity).","Ensure the embedding model dimension matches the table's vector(n); re-create the column if you changed models.","Confirm queryName (if overridden) matches the function name in the database.","For transient failures, retry."],"exampleFix":"// before — default RPC missing / dimension mismatch\nconst store = new SupabaseVectorStore('docs', { url, apiKey, tableName: 'docs' });\n// embedding model changed to 1536-dim but column is vector(384)\n\n// after — recreate column and RPC at the right dimension\n/*\nALTER TABLE docs ALTER COLUMN embedding TYPE vector(1536);\nDROP FUNCTION match_documents;\nCREATE FUNCTION match_documents(query_embedding vector(1536))\nRETURNS TABLE (id text, content text, metadata jsonb, similarity float)\nLANGUAGE sql STABLE AS $$\n  SELECT id, content, metadata, 1 - (embedding <=> query_embedding) AS similarity\n  FROM docs ORDER BY embedding <=> query_embedding;\n$$;\n*/","handlingStrategy":"try-catch","validationCode":"function assertSupabaseQueryConfig(opts: { url: string; apiKey: string; tableName: string; queryName?: string }): void {\n  if (!/^https?:\\/\\/.+/.test(opts.url)) throw new Error('Supabase url missing/invalid');\n  if (!opts.apiKey) throw new Error('Supabase apiKey missing');\n  if (!opts.tableName) throw new Error('Supabase tableName missing');\n  if (opts.queryName && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(opts.queryName)) {\n    throw new Error(`Invalid RPC name \"${opts.queryName}\"`);\n  }\n}\n\nassertSupabaseQueryConfig(opts);","typeGuard":null,"tryCatchPattern":"try {\n  await store.search(query);\n} catch (err) {\n  const msg = err instanceof Error ? err.message : '';\n  if (/Could not find the function/.test(msg)) {\n    throw new Error('match_documents RPC missing — create it per the store docs');\n  }\n  if (/different.*dimension|dimensions don't match/i.test(msg)) {\n    throw new Error('Embedding dimension mismatch — re-create the vector column');\n  }\n  const transient = /network|timeout|fetch|ECONN|503|504|paused/i.test(msg);\n  if (transient) { /* retry with backoff */ } else throw err;\n}","preventionTips":["Create the match_documents RPC exactly as documented, with vector(n) matching your embedding model.","When changing embedding models, re-create the vector column and the RPC at the new dimension.","If you override queryName, ensure it matches a real PostgREST function name.","Retry only transient errors; classify 'function not found' / 'dimension mismatch' as configuration fixes."],"tags":["supabase","database","network","rls","vector-store"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}