filesystem: add scoped token denials and exit codes to troubleshooting - #23966
Conversation
Clarified token usage instructions and exit codes for better understanding.
ti-chi-bot
Bot
added
contribution
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. 📝 WalkthroughWalkthroughThe filesystem troubleshooting guide covers token validity and refresh outcomes, scoped-token denials, and exit codes 0–5. ChangesFilesystem troubleshooting
Priority: ⬇️ Low Estimated code review effort: 1 (Trivial) | ~5 minutes Change: Other Merge Risk: 🔵 Low · up to The new guide gives the wrong exit codes for scoped HTTP 403 and invalid-token HTTP 401 failures, potentially misdirecting troubleshooting and scripts that rely on those codes. Correcting both mappings is localized; runtime behavior is unchanged. Architecture SummaryArchitecture risk: 🔵 Low · up to The change affects 1 system. Changed systems: Architecture concerns Review detailsSystems and components
Before / after behavior
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
qiancai
added
translation/no-need
ti-chi-bot
Bot
removed
the
missing-translation-status
|
@guangleibao: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this: Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
|
||
| Then retry the token operation. A mount on another machine is not visible locally; coordinate rotation with that machine separately. | ||
|
|
||
| ## Scoped token is denied |
There was a problem hiding this comment.
| ## Scoped token is denied | |
| ## Scoped token access is denied |
|
|
||
| ## Scoped token is denied | ||
|
|
||
| A scoped token that is used beyond its scope fails with exit code 1, and the message is one of two. Most commands report `fs access denied`. `ti fs copy-file` often reports an empty `HTTP 403:` instead. |
There was a problem hiding this comment.
| A scoped token that is used beyond its scope fails with exit code 1, and the message is one of two. Most commands report `fs access denied`. `ti fs copy-file` often reports an empty `HTTP 403:` instead. | |
| A scoped token used outside its scope causes the command to exit with code 1 and report one of two messages. Most commands report `fs access denied`. `ti fs copy-file` can report an empty `HTTP 403:` instead. |
|
|
||
| A scoped token that is used beyond its scope fails with exit code 1, and the message is one of two. Most commands report `fs access denied`. `ti fs copy-file` often reports an empty `HTTP 403:` instead. | ||
|
|
||
| Both messages mean the same thing: the token does not allow this operation on this path. Neither one is a connectivity problem or a sign that the token is invalid. Check what the token allows before you change anything: |
There was a problem hiding this comment.
| Both messages mean the same thing: the token does not allow this operation on this path. Neither one is a connectivity problem or a sign that the token is invalid. Check what the token allows before you change anything: | |
| In this context, both messages indicate that the token does not allow this operation on this path. Neither one is a connectivity problem or a sign that the token is invalid. Check what the token allows before you change anything: |
| --output text | ||
| ``` | ||
|
|
||
| Compare the token scope with the path and the operation you used. `search` also requires `read`. A scoped token cannot list the file system root unless its allowed path is `/`. A scoped token cannot widen its own permissions, so generate a new one with the operations you need instead of trying to change the existing token. |
There was a problem hiding this comment.
| Compare the token scope with the path and the operation you used. `search` also requires `read`. A scoped token cannot list the file system root unless its allowed path is `/`. A scoped token cannot widen its own permissions, so generate a new one with the operations you need instead of trying to change the existing token. | |
| Compare the token scope with the path and the operation you used. `search` also requires `read`. A scoped token cannot list the file system root unless its allowed path is `/`. A scoped token cannot widen its own permissions, so use an owner token to generate a new scoped token with the operations you need instead of trying to change the existing token. |
| | Code | Meaning | What to do | | ||
| | --- | --- | --- | | ||
| | 0 | Success | Continue. | | ||
| | 1 | The request was valid and the runtime or the service refused it | Read the message. A scoped token denial, a missing payment method, and a display name conflict all land here. | |
There was a problem hiding this comment.
| | 1 | The request was valid and the runtime or the service refused it | Read the message. A scoped token denial, a missing payment method, and a display name conflict all land here. | | |
| | 1 | Runtime or remote API error | Read the message and address the reported runtime, network, or service error. Scoped token denials and some other service errors also use this code. | |
| | 1 | The request was valid and the runtime or the service refused it | Read the message. A scoped token denial, a missing payment method, and a display name conflict all land here. | | ||
| | 2 | The command or the profile configuration cannot be used | Fix the command or the profile. Unknown flag, missing required input, a region where `ti fs` is unavailable, or a token file with loose permissions. | | ||
| | 3 | Authentication failed | Check the token or the API key pair. | | ||
| | 4 | The account lacks permission for the operation | Ask an organization administrator. This is different from the data-path denial at 1. | |
There was a problem hiding this comment.
| | 4 | The account lacks permission for the operation | Ask an organization administrator. This is different from the data-path denial at 1. | | |
| | 4 | The account lacks permission for the operation | Ask an organization administrator. This is different from a scoped-token denial, which returns exit code 1. | |
Reason: "Data-path denial" is implementation-oriented terminology.
| | 4 | The account lacks permission for the operation | Ask an organization administrator. This is different from the data-path denial at 1. | | ||
| | 5 | The file system, token, or other resource named in the request does not exist | Check the ID. A path that does not exist inside a file system returns 1, not 5. | | ||
|
|
||
| One case does not follow the table. A deleted or disabled token is reported on the data path, so it exits 1 rather than 3. See [File system token is rejected](#file-system-token-is-rejected). |
There was a problem hiding this comment.
| One case does not follow the table. A deleted or disabled token is reported on the data path, so it exits 1 rather than 3. See [File system token is rejected](#file-system-token-is-rejected). | |
| A deleted or disabled file system token is an exception to the preceding table: file commands return exit code 1 rather than 3. See [File system token is rejected](#file-system-token-is-rejected). |
| | --- | --- | --- | | ||
| | 0 | Success | Continue. | | ||
| | 1 | The request was valid and the runtime or the service refused it | Read the message. A scoped token denial, a missing payment method, and a display name conflict all land here. | | ||
| | 2 | The command or the profile configuration cannot be used | Fix the command or the profile. Unknown flag, missing required input, a region where `ti fs` is unavailable, or a token file with loose permissions. | |
There was a problem hiding this comment.
| | 2 | The command or the profile configuration cannot be used | Fix the command or the profile. Unknown flag, missing required input, a region where `ti fs` is unavailable, or a token file with loose permissions. | | |
| | 2 | Local usage, validation, or configuration error | Fix the command or the profile. Examples include an unknown flag, missing required input, an unsupported region, or a token file with loose permissions. | |
[LGTM Timeline notifier]Timeline:
|
|
@qiancai applied all eight suggestions. The exit code descriptions now follow the CLI spec you linked, which also confirms code 5 as |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
🟡 Minor · Document the token error as exit code 3. · filesystem-troubleshooting.md:62-63
tidb-cloud-filesystem/filesystem-troubleshooting.md:62-63
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDocument the token error as exit code 3.
When a deleted or disabled filesystem token causes an HTTP 401, the v0.2.4 CLI maps the response to exit code 3. Filesystem-specific bearer-auth handling changes the message, but does not remap the status to exit code 1.
Suggested fix
-If a file command reports `invalid API key` and exit code 1 while you are passing a file system token, check the token status before you look at your API key pair. A deleted or disabled token produces this message even when the API key pair is correct. +If a file command reports `invalid API key` and exit code 3 while you are passing a file system token, check the token status before you look at your API key pair. A deleted or disabled token produces this message even when the API key pair is correct.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: pingcap/docs/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: b1ddbe39-93e9-4924-8755-57acd95449da
📒 Files selected for processing (1)
tidb-cloud-filesystem/filesystem-troubleshooting.md
Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.
|
@qiancai: Your lgtm message is repeated, so it is ignored. DetailsIn response to this: Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: qiancai The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
3 participants
What is changed, added, or deleted? (Required)
Three fixes, measured with
ti0.2.4 on macOS 14.6, regionaws-us-west-2, 2026-09-27.1. No entry for a scoped token denial, which is the first failure a delegated user or an agent hits.
Across 25 denied combinations of command, path, and scope, every one exits 1, and the message splits by command rather than by path. Eight commands (
list-files,read-file,delete-file,create-directory,move-file,describe-file,find-files,search-file-content) reportfs access denied.copy-filereports an emptyHTTP 403:when uploading to, downloading from, or copying to an out-of-scope path, andfs access deniedwhen copying from one.The empty 403 gives the reader nothing and looks like a network fault. The new section says both messages mean the same thing, and adds two rules that are easy to miss:
searchrequiresread, and a scoped token cannot list the root unless its allowed path is/. The uneven message itself is a CLI issue, which I am filing separately.2. The docset never states the exit codes, so automation has to match error strings instead.
ti fsuses six, counted across every command in my local log, over 900 runs. The new table gives each code, its meaning, and the action.Codes 1 and 4 both look like permission problems: 1 is a data-path denial the caller can often fix, 4 means the account lacks the permission. A new paragraph also notes that a deleted or disabled token fails with
invalid API keyand exit 1 rather than an authentication error, so readers stop checking API keys that were never involved.I scoped the table to
ti fs, becauseti-cli-reference.mddocuments 130 for an interruptedti configure. If you would rather have one list for the whole CLI, I can move the table there and leave a link here.3. Two dense paragraphs in "File system token is rejected", one of which carried the whole
fs.token_refresh_ambiguouscase in a single sentence. Regrouped into one paragraph per job, keeping every fact.Which TiDB version(s) do your changes apply to? (Required)
The
tidb-cloud-filesystemdocset exists only onrelease-8.5, so no other branch applies.What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit