The server cannot find at least one version token requested by the client, causing the session to abort.
MySQL error 3137 ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND occurs when the version_tokens_session variable lists tokens the server does not have. Add or correct the missing version token on the server, or remove it from the client request, then retry to resolve the issue.
ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND
Error 3137 is raised by the MySQL Version Tokens plugin when a client session asks the server to match specific version tokens but the server cannot find one or more of them. The plugin guarantees application compatibility during rolling upgrades, so a missing token prevents the session from proceeding.
The error message returned is "Version token %.*s not found." and it is tagged with SQLSTATE HY000, indicating a general runtime failure rather than a syntax problem.
The error appears immediately after a client executes SET SESSION version_tokens_session='token1,token2' or uses another interface that implicitly sets this variable. If the server has not been configured with every listed token, MySQL terminates the statement with error 3137.
The condition was introduced in MySQL 5.7.8 alongside the version_tokens plugin and continues to exist in later versions that compile this plugin.
A missing token blocks the session from running subsequent queries, breaking application logic that relies on strict version compatibility. In production rollouts, unresolved tokens can stall blue-green or rolling deployments.
Correcting the token list quickly restores application availability and preserves the safety guarantees that version tokens provide.
The most common trigger is forgetting to add a new token on the server after deploying an application build that requires it. The client lists the token, but the server's token registry is outdated.
Another frequent cause is typographical errors in the token name or value supplied by the client. Because matching is exact, any mismatch leads to error 3137.
Disabling or not loading the version_tokens plugin on the server also causes the plugin to return an empty list, which will never satisfy client requests.
The fastest fix is to add the missing token on the server using VERSION_TOKEN_ADD() if the plugin is loaded:
SELECT VERSION_TOKEN_ADD('my_app','1.3.4');
If the plugin is not loaded, install it and restart MySQL:
INSTALL PLUGIN version_token SONAME 'version_token.so';
SET GLOBAL version_token='my_app:1.3.4';
As an alternative, remove the token from the client request when strict matching is not required:
SET SESSION version_tokens_session='';
Rolling upgrade: Add new token values on every server before switching client traffic to avoid the error.
Staging vs production mismatch: Ensure both environments expose identical tokens or adopt environment-specific token sets in the client.
Galaxy SQL editor integration: Galaxy surfaces session variables and highlights plugin errors inline, so you can quickly identify the failing SET statement, add the token, and rerun queries without context switching.
Maintain a deployment script that updates version tokens on every MySQL instance before releasing a new build.
Store tokens in configuration management (Chef, Ansible, Kubernetes ConfigMaps) to keep server state consistent.
Monitor MySQL error logs or Galaxy's query history for ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND and alert engineers immediately.
ER_VTOKEN_PLUGIN_TOKEN_DUPLICATE: Raised when attempting to add a token that already exists. Remove or rename the duplicate token.
ER_VTOKEN_PLUGIN_NOT_LOADED: Happens when the version_tokens plugin is missing. Install the plugin and restart MySQL.
ER_VTOKEN_PLUGIN_MALFORMED_TOKEN: Indicates an invalid token format. Correct the token string before retrying.
The server was started without the token specified by the client, often after an incomplete rollout.
The token string in the version_tokens_session variable contains a typo or wrong case, leading to an exact-match failure.
The version_tokens plugin is disabled or failed to load, so the server reports no available tokens.
Different MySQL instances in a cluster expose different token sets, causing errors when sessions fail over.
Occurs when attempting to add a token that already exists. Remove or update the existing token.
Raised for invalid token syntax. Ensure token strings follow name:value format.
Warns that the plugin is deprecated in the current MySQL version. Plan for alternative consistency mechanisms.
Yes, consistency across development, staging, and production avoids unexpected token errors during deployments.
Set version_tokens_session to an empty string in the client or omit the variable entirely. This bypasses token matching for the session.
It aborts only the current statement. After correcting the token list, the same connection can continue executing queries.
Galaxy highlights failing SET statements inline, lets you edit and rerun them instantly, and tracks token mismatches in query history for quick debugging.
.avif)
.avif){kind=logo}
