Troubleshooting
Use the error and the request you sent to narrow the problem. Check the items below before retrying a write, because a lost response does not prove that the write failed.
Keep the status code and X-OC-Trace-Id response header when available. Send these, a redacted request and the time of the failure to support@originchaindb.com. Never send passwords or tokens.
- Identify the symptomKeep the exact error, timestamp and response status.
- Find the matching checkSeparate connection, credentials, schema, indexing and capacity issues.
- Correct the specific causeChange the reported field or setting, not unrelated configuration.
- Verify with a small operationReconcile an uncertain write before trying it again.
401 unauthorized on every call
Check that the request sends Authorization: Bearer <token> and that the token belongs to the selected instance. Use the complete address from Connect. If a token was shown only when created, create a replacement rather than expecting to reveal it again. Never include the token in a support message.
Cannot connect to host
Copy the complete OC_URL from Connect. Keep any path in that address; do not construct it from an instance name or tenant ID. Check DNS, network access and TLS separately. For a PostgreSQL client, use its separate host, port, username and password.
Schema registration returns 400 'unknown column type'
Read the field named in the error and compare its ty with the schema types. For example, use str instead of string, and i64 instead of int. A supported vector column type does not automatically populate the vector search index.
Schema registration returns 400 'invalid type: string, expected struct'
A relation target is an object, not a dotted string. Supply its namespace, table and primary-key field using the structure in schema relations. Validate the manifest before loading rows.
[[extractions.fts]] and [[extractions.vector]] blocks ignored
These extraction blocks are not part of the schema grammar. Use the separate full-text indexing and vector write endpoints. Reuse the source row ID so your application can open the matching record.
Row insert returns 400 type_mismatch
Compare the named field with the schema. A JSON number differs from a quoted number, and true differs from "true". Correct the value or intentionally change the schema; do not silently convert source values during a retry.
Row insert returns 400 fk_violation
The referenced row must exist. Load parent records before dependent records and check that their IDs match. Keep the constraint unless you have deliberately changed the data model.
Bulk insert is much slower than expected
Use the batch row endpoint instead of one request per row. Choose a bounded batch size, inspect each receipt and respect the request limits of your deployment. A streamed import can still fail or complete only partly.
Duplicate rows after a network retry
A timeout does not tell you whether a write committed. Look up the intended primary key before retrying. Use an idempotency key only where the endpoint explicitly supports it; it does not make every SQL statement or SDK call safe to replay. See retry handling.
HAVING or a window function over a JOIN returns 400
Some clauses work on one table but not in the same query as a join. Check the named limitation in the SQL reference. A useful alternative is to aggregate one side first and then join, if that rewrite keeps the result you need.
Vector topk returns 400 dim_mismatch
The query embedding must have the same number of dimensions as the stored vectors. If you change embedding models, prepare a new compatible index and re-embed the source content before switching reads.
Vector topk returns 400 metric_mismatch
Use the distance metric configured for that vector table. Choose the metric recommended by your embedding model, then use it consistently for writes and queries. Do not change it only on the search request.
Vector search returns fewer than k hits
The index may contain fewer than k matching records. A selective metadata filter can also reduce the candidate set. Check the stored vectors, filter and search settings before increasing k.
FTS search returns no hits for words that should match
First confirm that the text was indexed under the table and field you are querying. Then test a word you know appears in it. Indexing and query token handling must agree; do not assume a selectable language stemmer or lemmatizer exists on the HTTP endpoint. See full-text support.
FTS hits link to rows that don't exist
A full-text document ID is not proof that a source row still exists. Your application must keep the separate index and rows consistent. Remove stale index entries and check that new entries use the intended row IDs.
Graph neighbors returns empty
Check the relation name, direction and source column. Existing rows may need a supported backfill after a relation is added. Follow the relation guide and verify a known linked pair before running a larger traversal.
BFS takes a long time / times out
Limit both traversal depth and result size. Start with one hop, inspect how many links it returns, and expand only as needed. A graph with many links can grow quickly at each additional hop.
429 rate_limited on legitimate traffic
Honor Retry-After when supplied and reduce concurrent requests. Add bounded backoff for operations that are safe to retry. For a large import, use batches and inspect progress rather than sending a burst of individual writes. See rate limits.
Replication lag visible in the dashboard
Check which endpoint served the read and whether it is a replica. Replication can be asynchronous, so a recent write may not yet appear there. Use the supported primary-read path when your workflow requires the latest committed record; confirm the deployment’s consistency behavior.
PITR restore is taking longer than expected
Check the restore job status, the selected recovery point and the resources assigned to the destination. Available history and restore time depend on your deployment and backup configuration. A submitted restore is not a completed restore. See recovery checks.