What causes "Error creating workflow definition: %s/%d" in conductor-oss/conductor?

Verify Cassandra cluster health and that the conductor keyspace + workflow_def table exist (run the schema migration if missing).

conductor-oss/conductor · error · TransientException

Error creating workflow definition: %s/%d

Error message

Error creating workflow definition: %s/%d

What it means

Thrown when the Cassandra driver raises a DriverException (connection loss, timeout, node unavailable, consistency not met, etc.) while createWorkflowDef executes its INSERT. The DAO wraps it in a TransientException, signalling the failure is retryable and not caused by bad input.

Source

Thrown at cassandra-persistence/src/main/java/com/netflix/conductor/cassandra/dao/CassandraMetadataDAO.java:192

                        "Workflow: %s, version: %s already exists!",
                        workflowDef.getName(), workflowDef.getVersion());
            }
            String workflowDefIndex =
                    getWorkflowDefIndexValue(workflowDef.getName(), workflowDef.getVersion());
            session.execute(
                    insertWorkflowDefVersionIndexStatement.bind(
                            workflowDefIndex, workflowDefIndex));
            recordCassandraDaoRequests("createWorkflowDef");
            recordCassandraDaoPayloadSize(
                    "createWorkflowDef", workflowDefinition.length(), "n/a", workflowDef.getName());
        } catch (DriverException e) {
            Monitors.error(CLASS_NAME, "createWorkflowDef");
            String errorMsg =
                    String.format(
                            "Error creating workflow definition: %s/%d",
                            workflowDef.getName(), workflowDef.getVersion());
            LOGGER.error(errorMsg, e);
            throw new TransientException(errorMsg, e);
        }
    }

    @Override
    public void updateWorkflowDef(WorkflowDef workflowDef) {
        try {
            String workflowDefinition = toJson(workflowDef);
            session.execute(
                    updateWorkflowDefStatement.bind(
                            workflowDefinition, workflowDef.getName(), workflowDef.getVersion()));
            String workflowDefIndex =
                    getWorkflowDefIndexValue(workflowDef.getName(), workflowDef.getVersion());
            session.execute(
                    insertWorkflowDefVersionIndexStatement.bind(
                            workflowDefIndex, workflowDefIndex));
            recordCassandraDaoRequests("updateWorkflowDef");
            recordCassandraDaoPayloadSize(
                    "updateWorkflowDef", workflowDefinition.length(), "n/a", workflowDef.getName());

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Verify Cassandra cluster health and that the conductor keyspace + workflow_def table exist (run the schema migration if missing).
Check conductor.cassandra.* properties (hosts, port, keyspace, consistency levels).
Retry the create call with backoff - TransientException is retryable by design.
Increase write timeouts or lower write consistency if timeouts recur under load.

Example fix

// before: single shot, surfaces TransientException to caller
metadataDAO.createWorkflowDef(def);

// after: retry on TransientException with backoff
RetryUtils.retryOn(TransientException.class, 3, Duration.ofMillis(200),
    () -> metadataDAO.createWorkflowDef(def));

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight: ensure the Cassandra session is open before writing
if (cassandraSession.isClosed()) {
    throw new IllegalStateException("Cassandra session is closed; cannot create workflow def");
}

Try / catch

// Retry transient driver failures during create
int attempts = 0;
while (true) {
    try {
        metadataDAO.createWorkflowDef(def);
        break;
    } catch (TransientException e) {
        if (++attempts >= 3) throw e;
        Thread.sleep(200L * attempts);
    }
}

Prevention

Wrap metadata writes in a retry-with-backoff for TransientException.
Monitor Cassandra cluster health and connection-pool saturation.
Ensure schema migrations (keyspace + workflow_def table) run before startup.
Size write timeouts to your largest workflow-definition payload.

When it happens

Trigger: session.execute(insertWorkflowDefStatement.bind(...)) throws a DriverException during workflow-definition creation - e.g. coordinator unavailable, write timeout, or the session being closed.

Common situations: Cassandra node down or restarting; network partition between Conductor and the cluster; keyspace/table not yet created (schema migration not run); connection pool exhausted under load; read/write timeout on a large payload.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/10f9efa0b7d1ff84. Report an issue: GitHub.