Troubleshoot Database

Check scope, identity, schema, and query shape in that order. This sequence isolates most Database issues quickly.

Start with five checks

1. Confirm the site hostname.
2. Confirm the app slug and logical table name.
3. Confirm the request uses one current credential.
4. Confirm is_materialized is true for the table.
5. Confirm the payload fields and value types match the stored schema.

For list requests, begin with page=1, a small page_size, and stable ordering.

Match the symptom

Symptom	Check	Next action
401 Unauthorized	Credential type, value, and expiry	Send one supported credential or obtain a fresh one
403 Forbidden	Caller role, app, table, action, and row scope	Test the same operation with the intended policy and caller
404 Not Found	Site URL, app slug, table name, and record ID	Confirm each path segment with the same caller
Table not materialized	Table metadata and provisioning status	Confirm provisioning completed and is_materialized is true
400 Bad Request on a write	Body shape, required fields, value types, and constraints	Retry with the smallest record that satisfies the schema
limit/offset pagination is not supported	Pagination parameters	Use page and page_size
Empty list	App/table scope, caller policy, and filters	Remove filters one at a time while preserving caller and scope
More rows than expected	Filter field, operator, value encoding, and combined filters	Rebuild the query from one exact-match filter and verify each addition
Unexpected order	ordering field names and direction prefixes	Add a stable tie-breaker such as id; use -field for descending
Create or update conflict	Primary key, unique values, and foreign keys	Generate a new key or update the intended existing record
Delete conflict	Referencing table and foreign-key action	Remove or reassign dependent records before retrying
504 Gateway Timeout	Page size, filters, relationship depth, and aggregation work	Reduce one dimension and retry the read
5xx response	Request identifier, timestamp, and operation	Read the target state before retrying a write

Reduce a list query

Use a fixed caller, site, app, and table while changing one query dimension at a time:

1. Request fields=id&page=1&page_size=1.
2. Add one exact-match root-table filter.
3. Add stable ordering.
4. Increase page_size.
5. Add one additional filter or a separately authorized related-table query.
6. Add grouping or aggregation last.

For ordinary record-list requests, compare data and total after each step; total is the number of matching records before the page is sliced. Grouped aggregate reads return a summary result set, and their total represents the number of returned group rows. See Aggregate records for the separate aggregate response contract.

Check a record write

For create and update requests:

1. Open Definition in TaruviBase Console and inspect the stored schema.
2. Confirm field names, types, required fields, and constraints.
3. Confirm the primary-key fields and types used by the table.
4. For a new single-key table, omit id to use TaruviBase's generated UUID or supply a valid UUID when the application owns the identity.
5. Remove fields that are not declared in the schema.
6. Create one synthetic record before sending a batch.
7. Read the record back and compare the stored values.

A single create returns the new record at data[0]. A single update returns the record directly in data. See Requests, responses, and errors for every response shape.

Check SDK behavior

• Confirm the installed SDK version matches the version declared on the page.
• JavaScript uses from(), pageSize(), and groupBy().
• Python uses from_(), page_size(), and group_by().
• Finish a query-builder operation with execute() unless the example uses first() or count().
• Refine Database examples use the read path: getList, getOne, and getMany through the corresponding useList, useOne, and useMany hooks.
• Compare an SDK request with the corresponding REST example when isolating route or query-parameter behavior.

Prepare a support request

Include:

• HTTP status, error code, and redacted message;
• UTC timestamp;
• site hostname, app slug, and logical table name;
• HTTP method and route;
• SDK or provider name and version; and
• a minimal synthetic payload or query.

Keep the support bundle safe by redacting API keys, tokens, cookies, personal data, and raw customer records.

For query syntax, continue with Filter, sort, and paginate records.