Provisioning and configuration

Database creation and configuration are workflow-backed. A form submission first validates product, role, billing, and provider constraints; accepted work then moves through a durable workflow. Diagnose the stage that failed before resubmitting.

Capture the current state first

Record the database name and UUID, organization slug, provider/region shown in Parix, plan, UTC time, exact message, and any workflow or provisioning-job ID. Then compare these surfaces:

• Database Dashboard: overall state and latest provisioning error;
• Cluster > Changes: up to the latest 100 durable changes with status, actor, start, and end times; and
• GET /api/v1/databases/{databaseId}: database/profile, latest provisioning job, provider, decommission, and metric-summary state.

Dashboard states have different meanings:

Do not interpret the existence of a database record—or an HTTP 200 create response—as proof that the deployment is ready.

Create is blocked before provisioning starts

Symptom. Create returns an eligibility/billing message, rejects a selection, or completes without a queued provisioning job.

Likely cause. The organization cannot use the selected plan, the name conflicts, a submitted catalog ID is stale, or the provider path did not enqueue. A create response can also report success: true while provisioning is failed_to_enqueue because the database record was created before the queue step failed.

Exact checks.

1. Read the complete create response, including success, message, billing, database/profile data, job data, and provisioning status.
2. If billing is present, record its code and message; verify that its checkout action matches the intended organization and plan.
3. Fetch GET /api/v1/catalog/create again. Confirm that the submitted provider, region, cluster configuration, cluster size, storage tier, and storage size appear together in the current catalog. The catalog does not return plan codes; verify the requested plan in the create response and billing state.
4. Check the database list for an existing record with the submitted name before retrying.
5. If a database ID was returned, retrieve that database and inspect its latest provisioning job.

Recovery. Resolve the billing/eligibility action or select one valid configuration from the refreshed catalog. If a database record already exists, keep its UUID and use the dashboard's Try Again action when offered for a failed profile; do not submit another create request simply because enqueueing failed. If the response says the provider was skipped or pending, follow that message and choose only a currently cataloged path.

When to contact support. Escalate when the current catalog accepts a configuration but enqueueing repeatedly fails, or billing state contradicts the dashboard. Include organization slug, database UUID if created, sanitized create response, catalog retrieval time, selected catalog IDs, UTC time, and latest job ID.

A TigerBeetle import is rejected

Symptom. The import form rejects uploaded files or does not start provisioning.

Likely cause. The upload is incomplete, the files are not a compatible complete replica set, or their embedded TigerBeetle version is newer than the platform target.

Exact checks.

1. Confirm every filename uses the .tigerbeetle extension and every upload session reports completed.
2. Count the files. The count must equal the node/replica count of the selected topology.
3. Confirm every file has a readable superblock.
4. Compare embedded cluster ID, TigerBeetle version, and replica count across all files; they must match.
5. Confirm replica indexes are unique and form the complete sequence from 0 through replica_count - 1, with no missing or duplicate index.
6. Confirm the embedded replica count matches the selected topology and the imported version is not newer than the target offered by Parix.

Recovery. Re-export or select the complete set from one cluster snapshot and upload every file again in one completed session. Choose the topology that matches the files. If the source TigerBeetle version is newer than the target, wait for/select a compatible platform target rather than modifying binary metadata.

When to contact support. Escalate when a verified complete set is rejected. Include file count, filenames, sizes, source TigerBeetle version, expected replica indexes, selected topology, upload-session ID, exact validation message, and UTC time. Do not attach ledger data unless support explicitly provides an approved secure transfer method.

Provisioning stays in progress or reaches Error

Symptom. The Dashboard remains Provisioning, shows Error, or offers Try Again after a create/configuration request.

Likely cause. A workflow is still queued/running, a provider step failed, or the database record/profile was created but its workflow could not be enqueued or completed.

Exact checks.

1. Open Cluster > Changes and locate the newest matching change. Check whether it is Pending, In progress, Completed, or Failed.
2. Compare its start/end time with the Dashboard's latest error and the API's latestProvisionJob.
3. Confirm that the profile is not already active; stale browser state can lag the durable job state.
4. If the original response reported failed_to_enqueue, verify that no newer job has appeared before attempting recovery.
5. Preserve the exact provider/workflow error rather than reducing it to “provisioning failed.”

Recovery. Refresh the Dashboard after confirming the durable change state. For a failed profile, use Try Again only when Parix offers it and no newer workflow is active. Correct any named configuration/billing prerequisite first. Do not issue concurrent create, topology, storage, backup, restore, or deletion requests while a provisioning workflow is active.

When to contact support. Escalate a failed workflow without an actionable recovery message, a job that makes no progress beyond the expected operational window, or conflicting Dashboard/Changes/API states. Include database UUID, provider/region shown, workflow/job ID, state transitions with UTC times, and exact error.

Configuration controls are missing or disabled

Symptom. Cluster, backups, logs, webhooks, upgrade, topology, storage, parameter, or CDC controls do not appear or cannot be selected.

Likely cause. The surface is not included with Shared Developer, your role cannot change control-plane state, the profile does not exist/is provisioning, or a conflicting workflow is active.

Exact checks.

1. Check the plan shown on the database Dashboard. Shared Developer exposes Connect, Dashboard, project Metrics, Query, and Settings; it does not expose dedicated Cluster, Logs, Backups, Webhooks, or CDC controls.
2. Confirm you are an organization owner or administrator. Control-plane mutations are not available to ordinary members.
3. Confirm that a profile exists and is active rather than provisioning.
4. Check Cluster > Changes and the relevant Backup/Restore status for an active conflicting workflow.
5. Check the current create catalog and active profile instead of assuming that a provider capability is enabled in this environment.

Recovery. Use the surfaces supported by the current plan or move through the product's supported plan path. Have an owner/admin perform the change. Wait for the active workflow to finish before returning to the same configuration tab.

When to contact support. Escalate when an owner/admin on an eligible dedicated database with an active profile cannot access a capability shown for that active provider. Include plan, role, database UUID, provider/region, profile state, UTC time, and screenshot.

Parix reports “No changes to queue”

Symptom. A topology, storage, or parameter form submits but no workflow starts.

Likely cause. The normalized submitted values equal the active profile. Parix deliberately avoids creating no-op workflows.

Exact checks.

1. Compare every submitted value with the active values displayed after a page refresh.
2. For storage, compare both tier/backend and capacity.
3. For topology, compare node count and cluster size—not only the visual option label.
4. For parameters, check normalized units, for example 512MiB, and whether empty/default values resolve to the active value.

Recovery. No recovery is needed if the active state is already the desired state. If a real change is intended, change the specific supported value and submit once.

When to contact support. Escalate when the refreshed active profile differs from the submitted value but Parix still reports no effective change. Include before/after values, database UUID, provider, screenshot, and UTC time.

A topology or storage change is rejected

Symptom. Parix refuses a node-count, cluster-size, storage-tier, backend, or disk-size change.

Likely cause. The requested transition is unsafe or not implemented for the active provider/storage backend. Provider implementation does not guarantee that the provider is available for new creation; the current catalog remains authoritative.

Exact checks.

1. Read the provider and storage backend from the active profile.
2. Re-read the exact rejection message and identify whether it concerns shrink, backend migration, local NVMe, or restore-backed migration.
3. For a GCP profile:
   • topology changes use a backup-driven migration;
   • disk capacity can grow but not shrink;
   • migration to or from Hyperdisk or Local NVMe is blocked in place; and
   • Local NVMe topology/size changes are blocked after creation in the current version.
4. For an existing AWS profile:
   • topology and storage changes remain blocked until the corresponding backup-driven restore migration is supported; and
   • Local NVMe post-create topology/size changes are blocked.
5. Confirm there is no active provision, backup, restore, import, or decommission workflow.

Recovery. Choose a supported grow-only/in-place transition. When Parix says a backend transition requires a new cluster, provision a new compatible database and use an approved migration/import workflow rather than trying to mutate the existing disks. Do not select an unavailable provider as a workaround.

When to contact support. Escalate when a transition documented as supported for the active profile is rejected. Include database UUID, active and requested topology/storage values, provider/region, backend, workflow state, exact error, and UTC time.

A parameter change or upgrade is rejected

Symptom. Parameter controls are absent, a cache value is invalid, or an upgrade/configuration workflow will not start.

Likely cause. Parameter changes are supported only for eligible GCP profiles, the value format is invalid, your role/plan/profile state blocks the action, or another workflow is active.

Exact checks.

1. Confirm the active profile's provider and that the current catalog/product surface offers the action.
2. Confirm owner/admin role, dedicated plan, active profile, and no conflicting workflow.
3. Enter cache-grid values in the accepted unit format, such as 512MiB.
4. Compare the requested TigerBeetle version/parameters with the active values to rule out a no-op.
5. Check Cluster > Changes for an existing upgrade or parameter change.

Recovery. Correct the value format or wait for the current workflow. Submit a supported change once. If the provider does not support in-place parameters, keep the active configuration or use a supported replacement/migration path.

When to contact support. Escalate when an eligible owner/admin cannot queue a supported non-no-op change. Include database UUID, provider, active/requested value or version, role, workflow list, exact message, and UTC time.

Deletion is queued, deferred, or failed

Symptom. DELETE /api/v1/databases/{databaseId} returns queued but the database remains, a repeat request returns 409, or the Dashboard shows Delete failed.

Likely cause. Deletion is asynchronous. Parix defers destructive work while provisioning is active, rejects duplicate active deletion requests, and surfaces provider workflow errors as Delete failed.

Exact checks.

1. Keep the workflowId from the accepted delete response.
2. Check the database's decommission state and latest provisioning job through the API.
3. Check Cluster > Changes for the provisioning workflow that may need to finish first.
4. If a repeat returned 409, confirm that the original decommission workflow is still active instead of issuing another request.
5. For Delete failed, record the exact provider/workflow error.

Recovery. Deletion is destructive and has no self-service undo. Before following an explicit retry, re-verify the database UUID/name and any export or recovery requirement. Allow active provisioning to reach a terminal state so deferred deletion can proceed. Do not use repeated DELETE calls as polling; retrieve the database state instead. Retry only after the failed workflow is terminal and its named cause is corrected. A late failure can occur after the database has already been hidden; in that case, contact support instead of recreating it. See Delete a database.

When to contact support. Escalate a terminal Delete failed state or a deferred request that does not resume after provisioning finishes. Include database UUID, delete workflow ID, provisioning job ID, decommission state, exact error, and UTC timeline.