# Troubleshooting


valiss verification fails closed, and every rejection has one specific cause.
This page maps the symptom you see (an HTTP status, a gRPC code, an error
string) back to what the verifier decided and what to check. The strings quoted
here come from the Go reference; the Python and TypeScript ports raise
`ValissError` whose `reason` is the same spec section 7 reason code, so the
causes apply to all three. Switch on `reason` rather than matching message text:
the code is stable, the message is illustrative.

The transports translate a verifier failure to a status once. `httpauth` answers
401 for an authentication failure and 403 for an extension denial; `grpcauth`
maps the same split to `Unauthenticated` and `PermissionDenied`. The response
body or status message carries the underlying cause.

## The client is rejected 401 but does send a token

**Missing credentials.** Symptom: 401 with `missing credentials` (gRPC
`Unauthenticated: missing credentials`). It means neither the account nor the
user token header reached the server, so the middleware rejects before
verifying anything. Check that the client uses a signing transport
(`httpauth.NewTransport`, `grpcauth.NewCredentials`, or the Python and
TypeScript auth hooks), and that no proxy strips the `valiss-account-token` and
`valiss-user-token` headers.

**Account token not recognized.** Symptom: 401, `account token not recognized`
(reason `not_allowlisted`). The account token verified against the pinned
operator key, but its `jti` is not in the server's allowlist, which fails
closed. Check that the `jti` the minter printed is the one loaded, that the
allowlist file was reloaded after any re-issue (issuing with different claims
produces a different `jti`), and that you did not mean to run `AllowAll`.

**Wrong operator pinned.** Symptom: 401, `account token not signed by the
expected issuer`. The account token was signed by a different operator than the
public key the server pinned. Check that the operator public key passed to
`NewVerifier` is the one that issued these account tokens, and in a
multi-operator deployment that the credential's trust domain is in the keyring.

## A token is expired or out of its window

Symptom: 401 with `account token expired`, `user token expired`, `account token
not yet valid`, or `operator token expired: the trust domain is closed`. A
token's `exp` or `nbf` fell outside the skew window (2 minutes by default); an
expired operator token closes the whole trust domain until a fresh one is
published. Check the clocks on the issuing and verifying sides, the TTL you
issued with, and whether an operator-token rotation ceremony was allowed to
lapse. `WithSkew` widens the tolerance when drift is unavoidable.

## Epoch mismatch after a rotation

Symptom: 401 with `account token epoch N, trust domain epoch M`, the same for a
user token, or `no trusted operator <key> at epoch N` (reason `epoch_mismatch`
or `unknown_operator`). The verifier enforces an operator token or keyring at
one epoch and the presented token carries another. This is the intended outcome
of an epoch bump: every earlier-epoch token is rejected cryptographically. To
resolve it, re-issue the account and user tokens at the current epoch. For a
grace period, register both the outgoing and incoming epochs in a `Keyring` so
the old epoch keeps verifying until its operator token's `exp` lapses. Unstamped
tokens are epoch 0.

## The request signature does not check out

**Signature required, not a bearer token.** Symptom: 401, `request signature
required: not a bearer token` (reason `not_bearer`). The request carried no
per-request signature and the effective token is not a bearer user token, so
possession is unproven. Check that the client creds carry a seed and sign
through the transport, or, for a client that cannot hold a key, issue the user
token with `WithBearer()` and pair it with TLS.

**Signature verification failed.** Symptom: 401, `request signature verification
failed` (reason `bad_request_signature`). The Ed25519 check over the
reconstructed request context failed, almost always because the server rebuilt
different context bytes than the client signed. The signature binds the method,
host, and path exactly. Check that no proxy rewrote the `Host` header or the
path, and that the host the client signed is the one the wire carries (an
explicit `Host` header wins, otherwise the URL host keeping any non-default
port). A captured signature cannot be reused across a different method or path.

**Timestamp outside the skew window.** Symptom: 401, `request timestamp outside
the 2m0s skew window` (reason `skew`). The client's request timestamp is too far
from the server's clock, or is unparsable. Check client clock sync, or widen the
verifier with `WithSkew`.

**Nonce required, or replay.** Symptom: 401, `request nonce required` or
`request nonce already seen (replay)`. The verifier runs a replay cache. The
first says the signed request carried no nonce; the second says the nonce was
already spent. Enable the nonce on the client (`httpauth.WithNonce()`, or
`nonce=True` in Python), and make each retry use a fresh nonce rather than
resend the identical request.

## The client is denied 403 (PermissionDenied)

**Request outside the extension.** Symptom: 403, `token does not permit GET
/admin`, or the gRPC form `token does not permit /pkg.Svc/Method`.
Authentication succeeded, but the request falls outside the token's HTTP or gRPC
extension bounds. Check the `Methods`, `Paths`, and (HTTP) `Hosts` on the token.
Each dimension is an AND-filter that constrains only when populated, and paths
take a trailing `*` prefix wildcard. Extensions on both the account and the user
token are enforced together, so an account-level cap bounds every user beneath
it.

**Token carries no extension.** Symptom: 403, `token carries no http extension`
or `token carries no grpc extension`. Transport enforcement fails closed, and
a token somewhere in the chain does not carry the transport extension at all.
Issue every token in the chain with the extension (the zero-value `Ext{}` grants
nothing; allow-all is the explicit wildcard `[]string{"*"}`). Only when
authorization lives entirely outside the transport, build the middleware with
`AllowMissingExtension()`.

## User-only credentials are rejected

Symptom: 401, `request carries no account token and the server has no account
token resolver` (reason `no_resolver`). The client sent only a user token and
the server cannot supply the matching account token. Configure
`WithAccountTokenResolver` (for example `StaticAccountTokens(...)`), or have the
client send a bundle that embeds the account token.

## A credentials file will not load

Symptom: `creds: no token markers found`, `creds seed: ...`, `creds token:
...`, or `creds: unsupported version N`. The file is not a valiss credentials file, a
token or seed block is corrupt, or it declares a format version this build does
not implement. Check that the file is the one the minter wrote, whole and
untruncated, that the seed and token blocks are intact base32, and that the
library is not older than the format that produced the file.

## Issuing a token errors

Issuance validates the key roles up front, so these fire at `Issue*`, not at
verify time:

- `account tokens must be signed by an operator-type nkey (expected an SO...
  seed)`, or `user tokens must be signed by an account-type nkey (expected an
  SA... seed)`: the signing key is the wrong level. The signer must sit exactly
  one level above the subject.
- `invalid tenant public key (expected an A... nkey)`, or `invalid user public
  key (expected a U... nkey)`: the subject public key is the wrong role.
- `audience, checksum, and chain apply only to message tokens`: `WithAudience`,
  `WithChecksum`, or `WithChain` was passed to an identity issuer.
- `message tokens must carry an expiry (WithTTL or WithExpiry)`: message tokens
  are short-lived by rule and cannot be issued without one.
- `duplicate extension "name"`: two extensions with the same `ExtensionName` on
  a single token.

## A message token will not verify

A message token is a proof of origin, verified offline; a `Verifier` never
accepts one as a credential. Its own failures:

- `missing message token` (httpsig, 401), or `message token chain required`
  (401): the receiver got no message token, or not the provenance chain it
  needs.
- `payload checksum mismatch` (reason `checksum_mismatch`): the body the
  receiver hashed differs from the one the emitter signed. Anything that
  re-encodes the payload in transit breaks it. For gRPC the checksum is over the
  deterministic protobuf encoding, so both ends must share the same message
  definition; a schema drift or a mismatched `google.golang.org/protobuf`
  produces different bytes and fails here.
- `message token audience "...", expected "..."` (reason `wrong_audience`): the
  token was issued for a different destination, or carries none while the
  receiver expects one. Set `ExpectAudience` to the destination you verify for.
- `message token expired`: a stored message was verified at `now` instead of its
  receipt instant. Pass `valiss.At(receivedAt)`.
- `message token carries no chain and none was supplied (WithChainTokens)`
  (reason `no_chain`): issue with `WithChain` to embed the provenance, or supply
  it out of band on the verify side with `WithChainTokens`.
- `message checksum requires a proto.Message, got T` (grpcsig): the value handed
  to the gRPC message signer is not a protobuf message.

## A token decodes but is rejected outright

- `unsupported wire version N`, or `unsupported token type`: the token comes
  from a wire version or envelope this build does not implement. `ver` is read
  from the header; the current version is 1.
- `token signature verification failed`, or `malformed token`: the token bytes
  are corrupt or were re-serialized. The signing input is the header and payload
  exactly as they appear on the wire, so a reparsed-and-re-encoded token no
  longer verifies.