Authentication failed. The server token may have changed.

Error message

Authentication failed. The server token may have changed.

What it means

handle_poll_error maps PollError::Auth to this message and exits with code 1 when the live poller's authentication with the local live server fails. The server token rotates or is regenerated on restart, so an old polling client is rejected.

Source

Thrown at crates/live/src/live_poll.rs:638

        .map(|t| EVENT_TYPES_NEEDING_AGENT_REPLY.contains(&t))
        .unwrap_or(false)
}

fn handle_event(mut event: Value, base: &str, token: &str, io: &mut Io) -> Value {
    if let Value::Object(obj) = &mut event {
        augment_event_with_accept_handling(obj, base, token, io);
        write_carbonize_banner(obj, io);
    }
    print_poll_event(&mut event, io);
    event
}

fn handle_poll_error(err: PollError, io: &mut Io) -> i32 {
    let cwd = io.cwd.to_string_lossy().into_owned();
    let env = io.env.clone();
    match err {
        PollError::Auth => {
            io.err("Authentication failed. The server token may have changed.\n");
            io.err(&format!(
                "Try restarting: {} stop && {}\n",
                script_cmd(&env, &cwd, "live-server"),
                script_cmd(&env, &cwd, "live")
            ));
            1
        }
        PollError::ConnRefused => {
            io.err(&format!(
                "Live server not running. Start one with: {}\n",
                script_cmd(&env, &cwd, "live")
            ));
            1
        }
        PollError::AckTimeout(m) => {
            io.err(&format!("{}\n", m));
            1
        }

View on GitHub (pinned to 2bc2879276)

Solutions

Restart both processes as the message suggests: run `<live-server> stop` then `<live>` again so the client picks up the fresh token.
Confirm the token/state files for this project match the running server's token.
Ensure only one live-server instance per project is running (duplicate instances can rotate tokens).

Example fix

// before
$ impeccable live  # poll with stale token
Authentication failed. The server token may have changed.
// after
$ impeccable live-server stop && impeccable live

Defensive patterns

Strategy: retry

Validate before calling

// Compare client token with the server's current token before polling
const clientToken = readStateToken();
const serverToken = readServerToken();
if (clientToken !== serverToken) console.error('token mismatch: restart live-server && live');

Try / catch

match poll_once(&session) {
  Err(PollError::Auth) => { restart_live_session(); retry(); }
  Err(other) => handle_poll_error(other, io),
  Ok(v) => v,
}

Prevention

Restart the poller together with the server (`live-server stop && live`) rather than reusing long-lived sessions.
Never hand-edit or copy token state files between projects.
Run one live-server per project to avoid token rotation races.

When it happens

Trigger: The `live` poll loop receives PollError::Auth — typically because the token persisted by the client no longer matches the live-server's current token after the server restarted or was reinitialized.

Common situations: Live server restarted while a stale poller/agent session kept the old token; multiple projects sharing state; manually editing or deleting the token/state file.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/549a46c98d628193. Report an issue: GitHub.