Skip to main content

Data Operations FAQ

Use the error message and load or query identifier to identify a failing operation. VeloDB Cloud manages frontend (FE) and backend (BE) services for SaaS and BYOC warehouses. Service configuration, host logs, node restarts, and replica repair require VeloDB Cloud support.

Q1. Why does Stream Load redirect to an unreachable address?​

Stream Load can return an HTTP 307 redirect to the selected upload address. Reaching the initial endpoint does not prove that the client can reach the redirected address.

Use the Stream Load URL generated for your warehouse and selected public or private connection. Check that your client follows redirects and that its DNS, proxy, firewall, and routing allow the complete upload path. Keep the generated scheme and port. If a public connection redirects to an unreachable private address, capture the redirect destination and contact VeloDB Cloud support.

See connection methods and Stream Load networking.

Q2. Can I rename a column?​

Yes. Use ALTER TABLE ... RENAME COLUMN for a supported column rename:

ALTER TABLE orders RENAME COLUMN old_name new_name;

Replace orders, old_name, and new_name with your table and column names. VeloDB Cloud enables the light_schema_change table property through managed property handling. Check the restrictions in ALTER TABLE RENAME before changing a column referenced by other objects or applications.

See schema changes for current behavior.

Q3. Can I create a materialized view on a Unique Key table?​

Yes, with restrictions that depend on the view type:

  • A synchronous materialized view must include every base-table key column and cannot perform aggregation. Its WHERE clause can reference only key columns.
  • An asynchronous materialized view can precompute query results and refresh them separately from base-table writes. Choose its refresh strategy according to your freshness requirements.

See synchronous materialized views and asynchronous materialized views.

Q4. What do load errors -235 and -238 mean?​

-235 indicates that a tablet has accumulated too many data versions. Frequent small loads can create versions faster than compaction combines them. Reduce load frequency and combine small batches. If the problem persists after load pressure decreases, provide the tablet ID, transaction ID, and error to VeloDB Cloud support.

-238 indicates too many segments in one rowset. Reduce the size of each batch and check for data skew or too few buckets distributing a large load. Choose batch sizes that avoid both excessive small transactions and oversized per-tablet writes.

The controls max_tablet_version_num, time_series_max_tablet_version_num, and max_segment_num_per_rowset are service settings. Request support review of a persistent limit error. See the Load FAQ.

Q5. What does tablet ... has few replicas mean?​

This message indicates that the operation could not select the expected tablet replicas or workers. Record the full error, tablet ID, affected table, selected cluster, and time of the failure. Check whether the cluster is running and whether other queries or loads are affected.

If the error persists, contact VeloDB Cloud support to inspect placement and worker health. Self-managed instructions for inspecting be.out, running dmesg, or changing replica status are not customer recovery procedures in VeloDB Cloud.

Q6. Why does a Java Stream Load client report Broken pipe?​

Broken pipe means that the connection closed during the request. It does not identify a single cause. Check whether the client handles the HTTP redirect and can reach the generated upload address. Also inspect client, proxy, and load-balancer timeouts, especially when small requests succeed but larger uploads fail.

Use a maintained HTTP client and compare the failing request with the generated Stream Load connection example. Record the response, elapsed time, request size, and any redirect before retrying. If the result is uncertain, check the load transaction or label first to avoid loading the batch twice. See the Stream Load result states.

For a VeloDB Cloud endpoint that still fails after client and network checks, contact VeloDB Cloud support.

Q7. What does error -214 mean?​

An error such as failed to initialize storage reader ... res=-214 indicates a missing data version for the requested tablet. Save the complete error, query or load ID, tablet ID, affected table, selected cluster, and timestamp.

Contact VeloDB Cloud support to investigate the tablet's metadata and storage state. Do not use self-managed replica-repair commands such as ADMIN REPAIR or ADMIN SET REPLICA STATUS as a Cloud recovery procedure. A missing-version error does not by itself establish whether source data must be reloaded.

Q8. What does Not connected to ... yet mean?​

This is an internal RPC connectivity error. Possible causes include an unavailable worker, congestion, or an oversized request. Save the full error and operation ID, including any OVERCROWDED or message-size detail.

Reduce excessive concurrent loads or split a very large batch, then check whether the symptom persists. If it does, contact VeloDB Cloud support. Settings such as brpc_socket_max_unwritten_bytes, tablet_writer_ignore_eovercrowded, and brpc_max_body_size require service-side diagnosis. Raising a transport threshold alone does not resolve congestion.

Q9. Why does Broker Load report a Thrift Broken pipe?​

org.apache.thrift.transport.TTransportException: java.net.SocketException: Broken pipe can occur when an external-storage operation times out or its connection closes. Large file listings are one possible cause.

Check the load job error and the source's availability, permissions, and file count. Use a narrower source path or split a large file set into separate loads. If the problem persists, provide the load label and source-path pattern to VeloDB Cloud support. Service-side timeouts such as broker_timeout_ms require support review.

Q10. How do I recover Routine Load from Broker: Offset out of range?​

The job's saved offset is outside the offsets currently available in Kafka. This can happen when a job stays paused longer than the topic's retention period. Check the topic's actual retention and earliest available offsets rather than assuming a fixed retention period.

Use a warehouse SQL user with LOAD privilege on the destination table.

  1. Inspect SHOW ROUTINE LOAD for the job state, progress, and pause reason.
  2. Determine the correct recovery offset for each affected partition. An earlier available offset can replay records. A later offset can skip records. Kafka cannot return records already removed by retention, so restore those records from another source if required.
  3. Pause the job if it is still running, then alter the affected partition offsets and resume it.

For example, after deciding to consume partition 0 from its earliest retained offset:

PAUSE ROUTINE LOAD FOR my_database.my_job;

ALTER ROUTINE LOAD FOR my_database.my_job
FROM KAFKA
(
"kafka_partitions" = "0",
"kafka_offsets" = "OFFSET_BEGINNING"
);

RESUME ROUTINE LOAD FOR my_database.my_job;

Replace my_database.my_job with your job name. If the job is already PAUSED, omit the PAUSE statement. OFFSET_BEGINNING means the earliest retained record, not the beginning of the topic's original history. Verify progress and destination data after resuming. See Routine Load.

Q11. How do I resolve a certificate verification location error?​

An error such as error setting certificate verify locations or curl 77: Problem with the SSL CA cert indicates that the component making the connection could not use the configured certificate trust material.

If the error is in your client, check its CA bundle and TLS configuration. If it is returned by a warehouse operation against external storage, provide the error and source type to VeloDB Cloud support for service-side trust-store checks. Keep certificate verification enabled. Installing packages or replacing files on FE and BE hosts is a managed-service operation.

Q12. What does the max_auto_partition_num limit error mean?​

Automatic partition creation checks the table's actual partition count against max_auto_partition_num. It does not count only the new partitions in the current load request.

Inspect the incoming partition-key values and the existing partitions with SHOW PARTITIONS FROM table_name. Unexpected dates or high-cardinality values can create more partitions than intended. Correct malformed source values and review the partitioning granularity. If the table needs more partitions, contact VeloDB Cloud support to review the service limit. See automatic partitioning.

Q13. What does disk ... on backend ... exceed limit usage mean?​

A worker storage-capacity check prevented the operation. Save the full error, query or load ID, and timestamp, then contact VeloDB Cloud support to investigate the worker's storage state and capacity.

VeloDB Cloud uses shared object storage for durable table data, but workers still use local storage for cache and temporary work. Do not apply self-managed cleanup instructions to worker directories. Deleting table data is not a substitute for diagnosing which storage area is full.