fix: preserve InfluxDB error bodies on the write path, fix zod packaging

handleWriteError discarded InfluxDB's response body and threw fixed
strings for 400/401/403/413/422, so 3.11's duplicate-tag-key rejection
never returned the tag name to the caller. Extract error normalization
into a shared error-resolution.service.ts (normalizeError,
resolveErrorMessage), add a 503 arm phrased as retryable, serialize
non-string bodies instead of rendering [object Object], and normalize
the cloud SDK's HttpError shape so Cloud Dedicated/Serverless reach the
same status arms as the axios-based paths.

Also moves zod from devDependencies to dependencies — it's imported at
runtime by every tool category module, so npm i --omit=dev previously
shipped a server that couldn't start.

Verified against live Core and Enterprise 3.11.2 (including a stopped
node on a 3-node Enterprise cluster). Bumps to 1.4.1.

Claude-Session: https://claude.ai/code/session_01JW2yQimGT2zarCwquDjKK8

Author: jstirnaman

CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to the official InfluxDB MCP Server will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1] - 2026-09-01
+
+### Fixed
+
+- **Write-path errors now preserve InfluxDB's error body.**
+  `write_line_protocol` discarded InfluxDB's response body on 400/401/403/413/422 and threw a fixed generic string instead.
+  A duplicate-tag-key write (rejected by InfluxDB 3.11+ before it reaches storage) now returns an error naming the tag.
+  For example, `Bad request: invalid line protocol - multiple instances of 'region' tag found`, instead of `Bad request: Invalid line protocol format or parameters`.
+  Verified against live Core and Enterprise 3.11.2.
+- **Added a 503 arm to the write error handler**, phrased as retryable (`Service temporarily unavailable, retry the write: ...`), so callers can distinguish a transient failure from a bad request.
+  Previously any unhandled status, including 503, fell through to the generic fallback.
+- **The write error fallback now serializes a parsed JSON body** instead of interpolating it directly.
+  The unserialized version previously rendered as `Failed to write data to database 'x': [object Object]`.
+- **Cloud Dedicated/Serverless write errors now classify correctly.**
+  The InfluxDB SDK throws `HttpError` (`error.statusCode`, `error.json`/`error.body`), a different shape than the axios-based Core/Enterprise/Clustered path (`error.response.status`/`.data`).
+  Every status branch previously missed on the SDK shape, so cloud writes always fell through to the generic fallback even for a 400 or 401.
+  Both shapes now normalize to one internal form before branching.
+- **`zod` moved from `devDependencies` to `dependencies`.**
+  It's imported at runtime by `src/tools/index.ts` and every tool category module.
+  A clean `npm i --omit=dev` install, or any consumer installing the published package, previously got a server that failed to start.
+- **8 transitive dependency vulnerabilities resolved** via `npm audit fix` (2 moderate, 6 high), all transitive through `eslint`/`vitest`.
+  No direct runtime dependency was affected.
+
+### Added
+
+- `src/services/error-resolution.service.ts`: shared error normalization (`normalizeError`, `resolveErrorMessage`) extracted from the write-path fix.
+  It follows the same body-resolution order `handleQueryError` already used.
+  It's available for the query path and the other services with their own ad hoc body-preserving variants (`token-management.service.ts`, `database-management.service.ts`, `cloud-token-management.service.ts`) to adopt in a later pass.
+
 ## [1.4.1-test.1] - 2026-07-30
 
 ### Changed

README.md

@@ -443,6 +443,34 @@ await mcp.update_database({
 - For connection issues, check your environment variables and InfluxDB instance status.
 - For advanced configuration, see the comments in the example `.env` and MCP config files.
 
+### Write errors
+
+`write_line_protocol` surfaces InfluxDB's own error text, not a generic
+message. If InfluxDB rejects a write — a duplicate tag key, an
+unauthenticated token, a payload over the size limit — the tool error
+includes the specific reason, for example:
+
+```
+Bad request: invalid line protocol - multiple instances of 'region' tag found
+```
+
+A `503` reaching this server is phrased as retryable
+(`Service temporarily unavailable, retry the write: ...`) — safe to retry
+the write. Any other status is not.
+
+### InfluxDB 3.11 compatibility
+
+Verified against InfluxDB 3.11.2 Core and Enterprise (including a
+multi-node Enterprise cluster). Core and Enterprise write through
+`POST /api/v3/write_lp`, which 3.11's write-availability changes for the
+legacy `/api/v2/write` endpoint do not affect; only `clustered` calls
+`/api/v2/write`. Query and schema-discovery tools behave the same whether
+the target database is on Parquet (Core, or Enterprise before an upgrade)
+or PachaTree (Enterprise 3.11+ by default, or after
+`--upgrade-pacha-tree`) — new `system.pt_*` tables are excluded from
+`get_measurements`/`get_measurement_schema` results by the same
+`table_schema = 'iox'` filter that already excludes other system tables.
+
 ---
 
 ## License

docs/adr/0002-shared-write-query-error-resolution.md

@@ -0,0 +1,58 @@
+# ADR 0002: Shared error resolution for the write and query paths
+
+- Status: Accepted (implemented for the write path in the 1.4.1 patch)
+- Date: 2026-09-01
+
+## Context
+
+`WriteService.handleWriteError` and `QueryService.handleQueryError`
+(`src/services/write.service.ts`, `src/services/query.service.ts`) both
+convert a thrown HTTP error into the error message returned to the MCP
+client. The two implementations diverged. `handleQueryError` resolves the actual InfluxDB
+error body (`data.message` → `data.error` → string body → `statusText` →
+`error.message`). `handleWriteError` matched only on
+`error.response?.status` and threw a fixed string per status; the response
+body was discarded. Its fallback interpolated `error.response?.data`
+directly, which rendered a parsed JSON body as `[object Object]`.
+
+InfluxDB 3.11 rejects a duplicate-tag-key write with a body that names the
+tag, nested under `data.data[].error_message`. The fixed 400 string
+discarded that body, so the tag name was not returned to the client. Neither
+handler had a 503 arm. The two write-capable transports throw different
+error shapes: axios (`error.response.status`/`.data`) for
+Core/Enterprise/Clustered, and the InfluxDB SDK's `HttpError`
+(`error.statusCode`, `error.json`/`.body`) for Cloud Dedicated/Serverless.
+`handleWriteError` matched only the axios shape, so cloud write errors
+always fell through to the fallback.
+
+Three other services preserve error bodies with their own separate
+implementations: `token-management.service.ts`,
+`database-management.service.ts`, `cloud-token-management.service.ts`.
+
+## Decision
+
+Extract the shared logic into `src/services/error-resolution.service.ts`:
+
+- `normalizeError(error)` converts the axios shape and the SDK `HttpError`
+  shape to one `{ status, body }` form.
+- `resolveErrorMessage(body, fallback)` resolves the error message from a
+  body: the write path's partial-write shapes first, then the query path's
+  existing resolution order, then `fallback`.
+
+`handleWriteError` calls both and switches on the normalized status,
+including a new `503` arm phrased as retryable. `handleQueryError` and the
+three token/database services are unchanged in this patch. The helper's
+default resolution order already matches `handleQueryError`'s current
+behavior, so migrating it, and the other three services, is deferred to a
+later change.
+
+## Consequences
+
+- One function defines the write path's error-body resolution for all five
+  product types, instead of five status arms each with its own field
+  access.
+- A future status code that needs a body-preserving arm extends
+  `resolveErrorMessage`'s resolution order once, for both paths.
+- `handleQueryError` and the three token/database services keep their own
+  implementations. That is a known follow-up, not a regression introduced
+  by this change.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@influxdata/influxdb3-mcp-server",
-  "version": "1.4.1-test.1",
+  "version": "1.4.1",
   "description": "Official InfluxDB MCP server for Model Context Protocol integration",
   "license": "(Apache-2.0 OR MIT)",
   "private": false,
@@ -63,7 +63,8 @@
     "@influxdata/influxdb3-client": "1.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "axios": "1.18.0",
-    "dotenv": "16.6.1"
+    "dotenv": "16.6.1",
+    "zod": "3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "9.39.4",
@@ -73,7 +74,6 @@
     "eslint": "9.39.4",
     "prettier": "3.8.1",
     "typescript": "5.9.3",
-    "vitest": "4.1.1",
-    "zod": "3.25.76"
+    "vitest": "4.1.1"
   }
 }

package.json

@@ -48,7 +48,7 @@ export function loadConfig(): McpServerConfig {
     },
     server: {
       name: "influxdb-mcp-server",
-      version: "1.4.1-test.1",
+      version: "1.4.1",
     },
     tools: {
       profile:

src/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared error normalization for the write and query paths.
+ *
+ * Two transports throw two different error shapes: axios (`error.response.*`)
+ * for the Core/Enterprise/Clustered HTTP paths, and the InfluxDB SDK's
+ * `HttpError` (`error.statusCode`, `error.json`/`error.body`) for the
+ * Cloud Dedicated/Serverless paths. `normalizeError` collapses both to one
+ * shape so status-branching code doesn't need to know which transport threw.
+ */
+
+export interface NormalizedError {
+  status: number | undefined;
+  body: unknown;
+}
+
+export function normalizeError(error: any): NormalizedError {
+  if (error?.response) {
+    return { status: error.response.status, body: error.response.data };
+  }
+  if (typeof error?.statusCode === "number") {
+    return { status: error.statusCode, body: error.json ?? error.body };
+  }
+  return { status: undefined, body: undefined };
+}
+
+/**
+ * Resolve the actionable message out of an InfluxDB error body.
+ *
+ * Write-path partial-write bodies nest the actionable detail under
+ * `data.data[].error_message` (when `accept_partial=true`, an array) or
+ * `data.data.error_message` (when `accept_partial=false`, an object) — one
+ * level below `data.error`, which is only ever the generic "partial write of
+ * line protocol occurred". Those two arms are checked first; query-path
+ * bodies never have a `data.data`, so they fall through unaffected.
+ */
+export function resolveErrorMessage(body: unknown, fallback: string): string {
+  if (body && typeof body === "object") {
+    const data = body as Record<string, unknown>;
+
+    if (Array.isArray(data.data)) {
+      const first = data.data[0] as Record<string, unknown> | undefined;
+      if (typeof first?.error_message === "string") return first.error_message;
+    } else if (data.data && typeof data.data === "object") {
+      const nested = data.data as Record<string, unknown>;
+      if (typeof nested.error_message === "string") return nested.error_message;
+    }
+
+    if (typeof data.message === "string") return data.message;
+    if (typeof data.error === "string") return data.error;
+    return fallback;
+  }
+
+  if (typeof body === "string") return body;
+  return fallback;
+}

src/services/error-resolution.service.ts

@@ -7,6 +7,10 @@
 
 import { BaseConnectionService } from "./base-connection.service.js";
 import { InfluxProductType } from "../helpers/enums/influx-product-types.enum.js";
+import {
+  normalizeError,
+  resolveErrorMessage,
+} from "./error-resolution.service.js";
 
 export type Precision = "nanosecond" | "microsecond" | "millisecond" | "second";
 
@@ -191,25 +195,27 @@ export class WriteService {
    * Centralized error handler for write methods
    */
   private handleWriteError(error: any, database: string): never {
-    if (error.response?.status === 400) {
-      throw new Error(
-        `Bad request: Invalid line protocol format or parameters`,
-      );
-    } else if (error.response?.status === 401) {
-      throw new Error("Unauthorized: Check your InfluxDB token permissions");
-    } else if (error.response?.status === 403) {
-      throw new Error(
-        "Access denied: Insufficient permissions for database operations",
-      );
-    } else if (error.response?.status === 413) {
-      throw new Error(
-        "Request entity too large: Reduce the size of your line protocol data",
-      );
-    } else if (error.response?.status === 422) {
-      throw new Error("Unprocessable entity: Invalid line protocol syntax");
+    const { status, body } = normalizeError(error);
+    const message = resolveErrorMessage(body, error.message);
+    switch (status) {
+      case 400:
+        throw new Error(`Bad request: ${message}`);
+      case 401:
+        throw new Error(`Unauthorized: ${message}`);
+      case 403:
+        throw new Error(`Access denied: ${message}`);
+      case 413:
+        throw new Error(`Request entity too large: ${message}`);
+      case 422:
+        throw new Error(`Unprocessable entity: ${message}`);
+      case 503:
+        throw new Error(
+          `Service temporarily unavailable, retry the write: ${message}`,
+        );
+      default:
+        throw new Error(
+          `Failed to write data to database '${database}': ${message}`,
+        );
     }
-    throw new Error(
-      `Failed to write data to database '${database}': ${error.response?.data || error.message}`,
-    );
   }
 }

src/services/write.service.ts

@@ -1,14 +1,13 @@
 /**
- * Packaging — `zod` is a misdeclared runtime dependency.
+ * Packaging — every runtime import must be a declared dependency.
  *
  * `zod` is imported at runtime by `src/tools/index.ts` and by every
- * `src/tools/categories/*.tools.ts`, but is declared in `devDependencies`. A
- * clean `npm i --omit=dev` — or any consumer installing the published package
- * — gets a server that cannot start.
+ * `src/tools/categories/*.tools.ts`. It used to be declared only in
+ * `devDependencies`, so a clean `npm i --omit=dev` — or any consumer
+ * installing the published package — got a server that couldn't start.
  *
  * The check is written as an invariant over every runtime import rather than
- * as a check on `zod` specifically, so it keeps working once `zod` moves to
- * `dependencies` and catches the next occurrence.
+ * as a check on `zod` specifically, so it catches the next occurrence too.
  */
 
 import { describe, it, expect } from "vitest";
@@ -69,34 +68,15 @@ describe("runtime imports are declared as dependencies", () => {
     expect([...imports.keys()]).toContain("zod");
   });
 
-  it("every runtime import except zod is declared in dependencies", () => {
-    // Current state. When zod moves to dependencies, this test fails and
-    // should be replaced by the assertion below.
-    const missing = [...imports.keys()].filter((n) => !declaredRuntime.has(n));
-
-    expect(missing).toEqual(["zod"]);
-  });
-
-  it("zod is imported at runtime but declared only in devDependencies", () => {
-    const zodImporters = imports.get("zod") ?? [];
-
-    expect(zodImporters.length).toBeGreaterThan(0);
-    expect(zodImporters).toContain("src/tools/index.ts");
-    expect(declaredDev.has("zod")).toBe(true);
-    expect(declaredRuntime.has("zod")).toBe(false);
-  });
-
-  it("the published package ships build/, so the import survives to consumers", () => {
+  it("the published package ships build/, so a missing dependency reaches consumers", () => {
     // Not a hypothetical: `files` includes `build`, and the compiled output
-    // keeps the bare `zod` specifier. The failure lands on the consumer.
+    // keeps every bare specifier. A misdeclared package lands on the consumer.
     expect(pkg.files).toContain("build");
     expect(pkg.main).toBe("./build/index.js");
   });
 });
 
-describe.skip("zod is a runtime dependency", () => {
-  // Un-skip when zod moves to dependencies, and delete the two
-  // characterization tests above that assert the opposite.
+describe("zod is a runtime dependency", () => {
   const imports = runtimeImports();
 
   it("no runtime import is missing from dependencies", () => {