Troubleshooting and FAQ¶

Fixes for the answers the MetaMiner Server (MMS) API gives most often, and short answers to common questions.

Quick reference¶

Symptom	Most likely cause	Entry
`401` on every call	Token missing, wrong, rotated, revoked or expired	401 Unauthorized
`401 API_AUTH_REQUIRED`	Local only mode, call from another machine	401 API_AUTH_REQUIRED
`403`	The client lacks the access the endpoint needs	403
`409 NOT_LEADER`	A write reached the standby node	409 NOT_LEADER
`503 API_CLIENTS_UNAVAILABLE`	Flow Scheduler switched on but not running on that node	503
`404` or `400` from `/tab/credentials`	Wrong environment, name mismatch, Tableau rejected the login	Tableau credentials

401 Unauthorized¶

401 on every call right after an upgrade

Cause: the old shared token file held no usable hash, so nothing was imported as the client api. The MMS log (server\logs\server.log) has a warning about it and the file was set aside.

Fix: create an API client in the MetaMiner Administrator (MMA) and give the script its token. See Upgrade from the Shared Token.

401 with a client you just created

Cause: the token was copied incompletely, or the client is expired or revoked. If the same token failed on that node in the previous 30 seconds, the node keeps refusing it until those 30 seconds have passed.

Fix: copy the whole mmsk_... token. Check Status and Expires in the API Clients window. Retry after 30 seconds.

401 after a rotation

Cause: a script still sends the old token. A rotation takes effect at once.

Fix: roll out the new token. See Rotate, Expire, Revoke.

To find refused calls, search the MetaMiner Server log for "rejected unauthorized": each line names the path and the caller's address. Tokens are never written to the log.

401 API_AUTH_REQUIRED¶

401 API_AUTH_REQUIRED from another machine

Cause: the authorization mode is Local only, which answers callers on the MMS machine only. Nothing was run or changed.

Fix: switch to API clients, restart MMS, and give the caller its own API client. See Authorization Modes.

403 Forbidden¶

403 on /tab/credentials, /fss/backup, /fss/v1/clients or /fss/v1/audit

Cause: the client is limited. Changing Tableau credentials needs an admin client without site limits (environment limits are allowed for those environments). Backups, client management and the audit need an admin client without environment or site limits.

Fix: use a client created in MMA (full access), or remove the limits with PUT /fss/v1/clients/{name}.

403 RUN_FORBIDDEN

Cause: a non-admin client's bound Tableau user may not run the flow, no Tableau user is bound, or trusted authentication is not set up on Tableau Server. A Tableau permission change can take up to a minute to count.

Fix: bind a Tableau user with run permission (tableauUsername), or use an admin client.

403 ENV_FORBIDDEN, SITE_FORBIDDEN or SITE_SCOPE

Cause: the client is limited to other environments or sites, or a site-limited client called a path not tied to one site.

Fix: call with an environment and site the client may use, or use a client without those limits. See Clients and Audit API.

409 NOT_LEADER¶

409 NOT_LEADER on a run, change or rotation

Cause: in a high-availability pair, writes are served by the Flow Scheduler leader. The call reached the standby; nothing was done there.

Fix: send it through the load balancer, or to the host named in leader. In MMA, manage API clients on the leader: on the standby the API Clients window is read-only and names the leader.

503 API_CLIENTS_UNAVAILABLE¶

503 API_CLIENTS_UNAVAILABLE

Cause: the Flow Scheduler is switched on but not running on that node, so MMS cannot check the API clients. MMS refuses rather than letting the call through. The MetaMiner Server log has a line containing "the API clients cannot be checked".

Fix: start the MetaMiner Flow Scheduler Service (MetaMinerFSS) on that node; calls succeed again at once. Retry after the Retry-After seconds. A load balancer that probes the Flow Scheduler sends calls to the other node meanwhile (see Load Balancer). While it is down, the API Clients window in MMA on that node is read-only.

Tableau credentials¶

404 from /tab/credentials

Cause: wrong envId, the environment is not configured on the MMS you called, or envName does not match the display name exactly (it is case-sensitive).

Fix: call GET /tab/credentials/status; it lists every Tableau Server environment's envId and envName. The environment does not need to be running.

400 Tableau REST API validation failed

Cause: Tableau rejected the new login. Nothing was applied or saved.

Fix: change the password in Tableau Server or your directory first, check that the account is not locked, then call again.

400 for a Tableau Cloud environment

Cause: the API changes Tableau Server logins only. Tableau Cloud signs in with a personal access token.

Fix: rotate the token in MMA. Nothing was changed by the call.

500 applied_not_persisted or persistence_unconfirmed

Cause: the new login is live, but saving it failed or was not confirmed within 10 seconds.

Fix: check the MetaMiner Server log, then call again so the change is saved. Until a save succeeds, an MMS restart brings back the old login.

The call is slow or times out

Cause: the call waits for a live Tableau sign-in and, in a high-availability pair, for the other node (30 seconds by default, up to 120 with waitSeconds).

Fix: set the client timeout above that wait, for example 180 seconds. Check connectivity from MMS to Tableau Server.

cluster is PENDING, PARTIAL or UNAVAILABLE

Cause: PENDING: another node has not applied the change yet, for example because it is down; it applies it when it is back. PARTIAL: a node did not take it; its message says why. UNAVAILABLE: the local Flow Scheduler did not answer, so only this node changed. On a single server with the Flow Scheduler switched off, UNAVAILABLE is the normal answer.

Fix: check GET /tab/credentials/status. For a node that missed the change, call POST /tab/credentials/sync. See Tableau Credentials API.

Other¶

413 Request body too large

Cause: every API request body is limited to 64 KiB; the limit is checked before the token.

Fix: send a smaller body.

Flow Scheduler API or backup calls fail

Cause: the Flow Scheduler is switched off, or not enabled for that environment (404 ENV_NOT_FOUND).

Fix: switch the Flow Scheduler on (see Enable the Flow Scheduler) and enable the environment (see Allowed Environments).

More codes: Status Codes and Errors.

FAQ¶

Do existing scripts break when we upgrade from the shared token?

No. The old shared token becomes the API client api and keeps working. See Upgrade from the Shared Token.

Can each script have its own token?

Yes. Create one API client per script or integration; each can be rotated or revoked on its own, and the audit names it.

Can MetaMiner show me a token again?

No. MetaMiner stores only a SHA-256 hash of each token. Rotate the client to get a new token.

Do I need to restart MMS?

Only after you change the authorization mode. Creating, changing, rotating or revoking a client takes effect without a restart, on every node.

Do I need the Flow Scheduler?

Not for the Tableau Credentials API or API clients: with the Flow Scheduler switched off, MMS keeps the clients itself. If the Flow Scheduler is switched on, it must be running for calls to that node to be authorized. The Flow Scheduler API and the backup API need it running.

Does the API work with Tableau Cloud?

The Tableau Credentials API changes Tableau Server logins only; rotate Tableau Cloud tokens in MMA. The Flow Scheduler supports Tableau Server only.

Which endpoints need a token?

In API clients mode, every MMS API endpoint: /tab/credentials, /fss/backup, /fss/v1/* (and the older /fss/run* paths). The load-balancer health probes need none.

Does a token expire?

Only if its client has an expiry. MMA offers none, 30, 90 or 365 days; over the API you set any expiresAt.

Which address do I call in a high-availability pair?

The load balancer, for every call except backups: call each node's own address to back up that node. The Tableau Credentials API works on either node and reaches the other.

Where do I see who called the API?

In MMA, API Clients > Audit Log..., or GET /fss/v1/audit. See Audit Trail.