{"record":{"id":"e79d77698df91417","repo":"influxdata/influxdb","slug":"series-key-mismatch-on-table-table-name-existing-table-has","errorCode":null,"errorMessage":"Series key mismatch on table {table_name}. Existing table has {existing}","messagePattern":"Series key mismatch on table (.+?)\\. Existing table has (.+?)","errorType":"validation","errorClass":"CatalogError","httpStatus":400,"severity":"error","filePath":"influxdb3_catalog/src/error.rs","lineNumber":197,"sourceCode":"        db_name: Arc<str>,\n        table_name: Arc<str>,\n    },\n\n    #[error(\n        \"Field type mismatch on table {} column {}. Existing column is {} but attempted to add {}\",\n        table_name,\n        column_name,\n        existing,\n        attempted\n    )]\n    FieldTypeMismatch {\n        table_name: String,\n        column_name: String,\n        existing: InfluxColumnType,\n        attempted: InfluxColumnType,\n    },\n\n    #[error(\n        \"Series key mismatch on table {}. Existing table has {}\",\n        table_name,\n        existing\n    )]\n    SeriesKeyMismatch {\n        table_name: String,\n        existing: String,\n    },\n\n    #[error(\"catalog subscription error: {0}\")]\n    Subscription(#[from] SubscriptionError),\n\n    #[error(transparent)]\n    Other(#[from] anyhow::Error),\n\n    #[error(\n        \"Cannot overwrite Processing Engine Trigger {} in Database {}\",\n        trigger_name,","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L179-L215","documentation":"InfluxDB 3's catalog enforces that a table's series key (the set of tag columns identifying a series) is fixed once the table is created. This error is thrown when a write attempt supplies data whose series key columns have types that conflict with the existing table definition, either a different key composition or an incompatible InfluxColumnType for an existing key column. It prevents silently corrupting the table schema.","triggerScenarios":"Writing lines via the line protocol / v1 / v3 write APIs where the tag set for the target table differs from the table's declared series key, or where a series key column's type differs from the existing InfluxColumnType (e.g. writing a field value into what was defined as a tag column, or a string vs integer conflict).","commonSituations":"Changing the tag set in a client's line protocol output after the table already exists; a script writing the same measurement with slightly different tag names; migrating data from InfluxDB 1.x/2.x where tags and fields were reshaped; typos in tag keys causing them to be treated as new series key columns.","solutions":["Inspect the existing table schema (SHOW or the catalog) and align your writes so tag columns exactly match the existing series key.","Fix the type of conflicting data on the client side (cast the value to the existing column's InfluxColumnType) before writing.","If the schema is genuinely wrong, create a new table (new measurement name) with the desired series key and rewrite/replay data into it; series keys cannot be altered in place.","Drop the table (if acceptable to lose data) and rewrite with the correct series key so it is recreated with the intended schema."],"exampleFix":"// before: line protocol with tag set that mismatches the table's series key\nweather,location=nyc temp=72\n// after: match the existing table's declared series key columns exactly\nweather,location=nyc,region=east temp=72","handlingStrategy":"validation","validationCode":"// Fetch the table schema and compare your write's tag set/types before writing\nconst schema = await client.getTableSchema(db, table);\nconst myTags = Object.keys(myLineTags).sort();\nconst existingKey = schema.seriesKeyColumns.sort();\nif (JSON.stringify(myTags) !== JSON.stringify(existingKey)) {\n  throw new Error(`series key mismatch: got [${myTags}], table has [${existingKey}]`);\n}","typeGuard":"function hasMatchingSeriesKey(myTags, existingKey) {\n  return Array.isArray(existingKey) &&\n    myTags.length === existingKey.length &&\n    [...myTags].sort().every((t, i) => t === [...existingKey].sort()[i]);\n}","tryCatchPattern":"try {\n  await client.write(db, lines);\n} catch (e) {\n  if (String(e).includes('Series key mismatch')) {\n    // refetch schema, realign tags/types, then retry once\n  } else throw e;\n}","preventionTips":["Freeze the tag set per measurement and version it alongside your writer code","Validate line protocol tags against the table schema in CI before deploying writers","Never send field data as tags after a table exists","Use distinct measurement names when restructuring tags instead of mutating an existing table"],"tags":["schema","influxdb","series-key","write-path"],"backgroundTag":"type-mismatch","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}