docs: expand SDK troubleshooting with runtime errors and platform-agnostic language#206
docs: expand SDK troubleshooting with runtime errors and platform-agnostic language#206marythought merged 9 commits intomainfrom
Conversation
…ostic language Adds Token Expired, TDF Format Error, and Entity Resolution Failed sections to cover runtime errors not previously documented. Updates Permission Denied to mention 'key access denied'. Adds Getting Help section. Generalizes all opentdf-local-dev-specific URLs, Caddy/installer references, and hardcoded namespaces so the page can be imported into DSP docs without modification. Closes DSPX-2426 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the SDK troubleshooting documentation by incorporating solutions for several common runtime errors and making the entire guide more universally applicable. The changes aim to provide clearer, more comprehensive guidance for users regardless of their specific deployment environment, improving the overall usability and relevance of the documentation. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the SDK troubleshooting documentation by adding new sections for common runtime errors like "Token Expired", "TDF Format Error", and "Entity Resolution Failed". It also improves existing sections, such as "Permission Denied", by including additional error messages. A new "Getting Help" section provides guidance on checking platform health and reporting issues. Crucially, the PR generalizes platform-specific language and URLs, replacing hardcoded values with placeholders, which makes the documentation more platform-agnostic and reusable. These changes are well-aligned with the goal of providing comprehensive and adaptable troubleshooting resources.
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Without authentication, the GitHub API caps at 60 req/hr per IP. When
exceeded it returns {"message": "API rate limit exceeded"} ��� not an
array — causing "contents is not iterable" and a build failure.
- Add githubHeaders() to send GITHUB_TOKEN when available (5000 req/hr)
- Add Array.isArray guard so rate-limit responses warn and skip instead of crash
- Add HTTP error handling in fetchJson/fetchText for 4xx/5xx responses
- Pass GITHUB_TOKEN to the build step in test-deploy.yaml
- Remove duplicate *.info.mdx files instead of silently skipping rename
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add 'attribute does not exist' error to Resource Not Found section (ticket error #9 was missing coverage) - Fix Keycloak-specific /realms/<realm> path in Token Expired JS example with a comment to adjust for other IdPs - Fix placeholder inconsistency: 'your-client-id' → '<your-client-id>' in Entity Resolution Failed section - Restore internal link in scope note as full URL so it works when imported into DSP docs - Add Windows PowerShell cert trust instructions to Certificate Errors - Replace duplicate health check code block in Getting Help with a prose reference to the Connection Refused section - Improve preprocessing.ts log message: 'stale duplicate' is clearer Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace --attribute-value-fqn with a jq lookup + --attribute-value-id in the Permission Denied and Entity Resolution Failed CLI examples. Both otdfctl and tructl support --attribute-value-id; tructl has no --attribute-value-fqn flag (tracked in DSPX-2529), so this approach works with both CLIs and removes the need for a special-case transform when importing into DSP docs. Also removes --namespace from the attributes list call; tructl has no --namespace filter flag (also tracked in DSPX-2529). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jp-ayyappan
left a comment
jp-ayyappan
left a comment
There was a problem hiding this comment.
Check comments first and verify before merge
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
marythought
dismissed stale reviews from jp-ayyappan and pflynn-virtru
via
9e0ecb7
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
marythought
dismissed stale reviews from pflynn-virtru and jp-ayyappan
via
69771ee
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3 participants
Summary
docs/sdks/troubleshooting.mdx: Token Expired, TDF Format Error, and Entity Resolution Failed — covering runtime errors from the DSPX-2426 top-10 list not previously documentedkey access deniedas another form of the error<platform-endpoint>/<idp-endpoint>/<kas-endpoint>, Caddy/installer-specific cert steps → generic trust instructions, docker compose restart → generic pointer to deployment docs,opentdf.ioexample namespace →example.com, hardcodedopentdfclientId →<your-client-id>Preview
https://opentdf-docs-preview-dspx-2426.surge.sh/sdks/troubleshooting
Test plan
/sdks/policy#create-subject-mapping,/sdks/discovery#validateattributes)/sdks/troubleshootingfor readabilityCloses DSPX-2426
🤖 Generated with Claude Code