Applies to VAST Cluster 5.5. Examples use the VAST DataBase Python SDK 2.1.0.
Find what you're seeing in the tables below. Each row gives the likely cause and links to the page with the details and the fix. If you have an exception, search the error reference for the last line of your traceback.
Connecting and permissions
| Symptom | Likely cause | Where to look |
|---|---|---|
connect() fails with ConnectionError |
The address or port is wrong, or the client can't reach the endpoint | Errors: connecting |
connect() fails with UnsupportedServer ... ("nginx") |
You used the management (VMS) address instead of a database VIP | Errors: UnsupportedServer |
connect() fails with Forbidden, code SignatureDoesNotMatch or InvalidAccessKeyId |
The secret key is wrong, or the cluster doesn't know the access key | Errors: Forbidden |
tx.bucket() fails with Forbidden and no code |
The identity policy doesn't allow s3:ListBucket |
Setup prerequisites: permissions |
Some calls work, but others fail with Forbidden and code AccessDenied |
The policy doesn't allow the action that operation needs | Setup prerequisites: actions each operation needs |
MissingBucket |
The database name is wrong | Errors: missing objects |
NotSupportedVersion |
The feature needs a newer cluster | Versions: SDK features that need a newer cluster |
Queries
| Symptom | Likely cause | Where to look |
|---|---|---|
NotImplementedError showing your filter |
The SDK can't push the filter down to the cluster. For example, an OR across two columns. | Querying: rewrite filters that don't push down |
| An exact decimal filter returns the wrong rows | SDK 2.1.0 converts decimal literals incorrectly | Data types |
MissingTransaction or TransactionNotActiveError |
You read results, or used a table, after its transaction ended | Transactions in practice: objects belong to their transaction |
| A query is slow | It asks for too many columns, its filter doesn't push down, or the table structure doesn't suit the query | Performance: ask for less, Data modeling |
QueryDataInternalError ... error_code=<n> |
The cluster aborted the query. Admin task: send to your platform team. | Errors: QueryDataInternalError |
Writes and imports
| Symptom | Likely cause | Where to look |
|---|---|---|
Conflict (409, TabularWwc) |
Another open transaction changed the same object or row | Transactions in practice: conflicts |
TabularTxAlreadyRollbacked at commit |
The cluster had already rolled your transaction back after a conflict | Errors: TabularTxAlreadyRollbacked |
update() fails with BadRequest, code InvalidArgument |
You changed a column that can't be updated: a sort, partition or vector column, or vastdb_rowid |
Updates and deletes: columns you can't update |
create_table(), add_sorting_key() or create_projection() fails with BadRequest, code InvalidArgument |
The table structures you're combining can't be combined | Limits: combining table structures |
TabularRowAllocMethodConflict |
You combined user-defined row IDs with a structure they can't be combined with, or inserted without vastdb_rowid into a table that uses them |
Data modeling: row IDs |
TooWideRow |
One row is too big for a request. Part of it may already be written. | Ingest: rows that are too big for one request |
import_files() raises NotFound (404) |
A file, or its bucket, doesn't exist | Errors: NotFound from import_files |
ImportFilesError with TabularMismatchColumnType or TabularMismatchColumnName |
The file's columns don't match the table's | Errors: ImportFilesError |
| Importing a file again adds no rows | The file was already imported. Check the imports table. | Ingest: see which files have been imported |
get_stats() shows 0 rows right after a commit |
Statistics are updated in the background, not at commit | Monitoring: table statistics |
Engines and clients
| Symptom | Likely cause | Where to look |
|---|---|---|
| A Trino or Spark connector doesn't work with your cluster | The connector version doesn't match the cluster version | Versions: connectors and cluster |
NoAdbcConnectionError |
No ADBC driver was available when the transaction started | ADBC: if the driver isn't there |
| A query returns fewer rows than you expect, or masked values | Row or column security applies to your user | Security: row and column security |
Before you ask for help
Collect:
- The exception's
code,message,statusandurl. - Your SDK and cluster versions; see find your versions.
- The time it happened.
The SDK's log lines include your endpoint address. Remove addresses and keys before you post logs anywhere; see reading an SDK error.