{"record":{"id":"d856ab096b4132fd","repo":"temporalio/temporal","slug":"unable-to-insert-custom-search-attributes-w","errorCode":null,"errorMessage":"unable to insert custom search attributes: %w","messagePattern":"unable to insert custom search attributes: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/persistence/sql/sqlplugin/mysql/visibility.go","lineNumber":118,"sourceCode":"\ttx, err := db.BeginTxx(ctx, nil)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tdefer func() {\n\t\terr := tx.Rollback()\n\t\t// If the error is sql.ErrTxDone, it means the transaction already closed, so ignore error.\n\t\tif err != nil && !errors.Is(err, sql.ErrTxDone) {\n\t\t\t// Transaction rollback error should never happen, unless db connection was lost.\n\t\t\tretError = fmt.Errorf(\"transaction rollback failed: %w\", retError)\n\t\t}\n\t}()\n\tresult, err = tx.NamedExecContext(ctx, templateInsertWorkflowExecution, finalRow)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to insert workflow execution: %w\", err)\n\t}\n\t_, err = tx.NamedExecContext(ctx, templateInsertCustomSearchAttributes, finalRow)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to insert custom search attributes: %w\", err)\n\t}\n\t_, err = tx.NamedExecContext(ctx, templateInsertChasmSearchAttributes, finalRow)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to insert chasm search attributes: %w\", err)\n\t}\n\terr = tx.Commit()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn result, nil\n}\n\n// ReplaceIntoVisibility replaces an existing row if it exist or creates a new row in visibility table\nfunc (mdb *db) ReplaceIntoVisibility(\n\tctx context.Context,\n\trow *sqlplugin.VisibilityRow,\n) (result sql.Result, retError error) {\n\tdefer func() {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/persistence/sql/sqlplugin/mysql/visibility.go#L100-L136","documentation":"The second statement of the InsertIntoVisibility transaction — inserting into the custom search attributes table (templateInsertCustomSearchAttributes) — failed. Because this happens inside a transaction, everything is rolled back and the error is wrapped as 'unable to insert custom search attributes'. This usually means schema drift on the custom search attributes table or invalid/oversized search attribute values.","triggerScenarios":"InsertIntoVisibility: templateInsertCustomSearchAttributes NamedExecContext returns an error — custom search attributes row violates constraints, custom search attribute keys exceed limits, or the table schema is out of date.","commonSituations":"Using custom SearchAttributes not supported by the SQL visibility store version; SA key names too long or with unsupported characters; visibility schema not migrated; timezone/datetime encoding issues in attribute values.","solutions":["Inspect the wrapped MySQL error to see the specific constraint or data issue.","Apply visibility schema migrations so the custom search attributes table matches expectations.","Validate search attribute keys/values conform to limits (key length, allowed types) before starting the workflow.","Confirm registered custom search attribute definitions match what the workflow emits.","Check DB connectivity if the wrapped error is a connection/driver error."],"exampleFix":"// before\nworkflowOpts.SearchAttributes = map[string]interface{}{\n    \"CustomIntField & Partner\": 42, // invalid key characters\n}\n\n// after\nworkflowOpts.SearchAttributes = map[string]interface{}{\n    \"CustomIntFieldPartner\": 42,\n}","handlingStrategy":"validation","validationCode":"// Go: validate SA keys before starting the workflow\nfor key := range searchAttributes {\n    if len(key) > 64 || strings.ContainsAny(key, \"& %$#@\") {\n        return fmt.Errorf(\"invalid custom search attribute key: %q\", key)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := db.InsertIntoVisibility(ctx, row); err != nil {\n    if strings.Contains(err.Error(), \"unable to insert custom search attributes\") {\n        logger.Error(\"custom SA insert failed; validate SA keys and schema\", tag.Error(err))\n        return convertPersistenceErr(err)\n    }\n    return err\n}","preventionTips":["Keep custom search attribute keys short and alphanumeric.","Match the visibility schema version to the server release before enabling custom SAs.","Test SA-heavy workflows against a staging DB with the same schema and SQL mode."],"tags":["mysql","visibility","search-attributes","schema"],"backgroundTag":"sql-insert-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}