Plainwork
Sign inStart free

Troubleshooting

Invalid token

Diagnose "invalid environment" at startup and 401/403 from the API.

Last updated

Invalid token

Two related failure modes:

  1. The server exits at startup with "invalid environment" — the token value is malformed or missing before any tool call is made.
  2. The server starts, but tools return "Plainwork API error (401)" or "(403)" — the token parsed locally but the API rejected it.

invalid environment at startup

The server validates PLAINWORK_API_KEY against the shape pw_agent_<suffix> before opening any transport. Any of the following aborts startup:

  • The env var is missing entirely.
  • The value does not start with pw_agent_.
  • The value is an empty string.

The log line looks like:

[plainwork-mcp] invalid environment:
  PLAINWORK_API_KEY: String must start with "pw_agent_"

Fix

  • Confirm the var is set in the right process. For Claude Desktop / Cursor, the env block in the JSON config is the only source — shell exports do not propagate into those subprocesses.
  • Re-paste the token from Plainwork → Settings → Agents. The token is shown once; if you lost it, rotate and re-paste.
  • Check for hidden characters from copy-paste (leading whitespace, a newline, smart quotes around the value in JSON).

Plainwork API error (401) or (403) at runtime

The server started, but the Plainwork API rejected a tool call.

  • 401 Unauthorized — the token shape is valid but the hash is not recognized server-side. Causes: token was rotated, agent was deleted, the token is from a different workspace.
  • 403 Forbidden — the token is valid but the agent is not allowed to perform that action (scope, collection ACL, or revoked after creation).

Fix

  1. Plainwork → Settings → Agents and check whether the agent still exists and is enabled.
  2. If the agent was deleted, create a new one and re-paste the token.
  3. If the agent exists but keeps returning 403 on a specific collection, verify the agent's scope in its settings.
  4. Rotate the token as a last resort — mints a fresh secret and invalidates any cached older value in wrappers or editors.