temporalio/temporal · error

unable to insert workflow execution: %w

Error message

unable to insert workflow execution: %w

What it means

InsertIntoVisibility executes a three-statement transaction: insert into the executions visibility table, then custom search attributes, then CHASM search attributes. This error wraps the failure of the first statement (templateInsertWorkflowExecution) via NamedExecContext and aborts the transaction. Typical causes are MySQL constraint violations, schema drift, or connection errors.

Source

Thrown at common/persistence/sql/sqlplugin/mysql/visibility.go:114

	if err != nil {
		return nil, err
	}

	tx, err := db.BeginTxx(ctx, nil)
	if err != nil {
		return nil, err
	}
	defer func() {
		err := tx.Rollback()
		// If the error is sql.ErrTxDone, it means the transaction already closed, so ignore error.
		if err != nil && !errors.Is(err, sql.ErrTxDone) {
			// Transaction rollback error should never happen, unless db connection was lost.
			retError = fmt.Errorf("transaction rollback failed: %w", retError)
		}
	}()
	result, err = tx.NamedExecContext(ctx, templateInsertWorkflowExecution, finalRow)
	if err != nil {
		return nil, fmt.Errorf("unable to insert workflow execution: %w", err)
	}
	_, err = tx.NamedExecContext(ctx, templateInsertCustomSearchAttributes, finalRow)
	if err != nil {
		return nil, fmt.Errorf("unable to insert custom search attributes: %w", err)
	}
	_, err = tx.NamedExecContext(ctx, templateInsertChasmSearchAttributes, finalRow)
	if err != nil {
		return nil, fmt.Errorf("unable to insert chasm search attributes: %w", err)
	}
	err = tx.Commit()
	if err != nil {
		return nil, err
	}
	return result, nil
}

// ReplaceIntoVisibility replaces an existing row if it exist or creates a new row in visibility table
func (mdb *db) ReplaceIntoVisibility(

View on GitHub (pinned to bde624efd1)

Solutions

1. Read the wrapped MySQL error in the message to identify the exact cause (dup key, data too long, unknown column).
2. Run the visibility schema migrations (temporal-sql-tool / schema setup) to ensure the visibility store matches the server's expected schema version.
3. Check row values: truncated/oversized SearchAttribute or workflow name data against column definitions.
4. Verify the visibility DB connection is healthy and using the correct database name in config.
5. If it is a duplicate-key style failure, confirm the caller semantics — for replace behavior use ReplaceIntoVisibility instead.

Example fix

// before: schema missing columns added in newer version
// visibility_workflow_executions lacks new SA columns

// after: apply the visibility schema update
temporal-sql-tool -plugin mysql -ep $DB_HOST -u $DB_USER -p $DB_PWD update-schema -d temporal_visibility

// Go: preflight schema version check
var v string
if err := visibilityDB.GetContext(ctx, &v, "SELECT version_ref FROM schema_version"); err != nil || v < requiredVersion {
    logger.Fatal("visibility schema out of date; run update-schema")
}

if err := db.InsertIntoVisibility(ctx, row); err != nil {
    if strings.Contains(err.Error(), "unable to insert workflow execution") {
        logger.Error("visibility insert failed; check wrapped MySQL error/schema", tag.Error(err))
        return convertPersistenceErr(err)
    }
    return err
}

When it happens

Trigger: Calling InsertIntoVisibility where the INSERT into the visibility executions table fails: duplicate row handling rejected by schema, column mismatch from an out-of-date schema (visibility schema version), too-long column values (e.g. WorkflowTypeName/Identifier over column size), or a lost connection.

Common situations: Visibility store schema not migrated after upgrading Temporal (missing new columns in visibility_workflow_executions); SQL mode strictness rejecting oversized data; connection issues to the visibility database.

Related errors

• unable to insert custom search attributes: %w
• unable to insert chasm search attributes: %w
• unable to upsert workflow execution: %w
• unable to upsert chasm search attributes: %w
• unable to upsert custom search attributes: %w

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/e84cad70bdd5b959. Report an issue: GitHub.