Summary
The Permission Denied / Insufficient Entitlements section in docs/sdks/troubleshooting.mdx (lines ~228-241) shows a subject-condition-sets create example that uses an incorrect flag name and an incorrect JSON shape:
otdfctl policy subject-condition-sets create \
--subject-set '[".clientId == \"<your-client-id>\""]' \
--label "My Service Account"
Two problems:
- Flag is
--subject-sets (plural), not --subject-set. See otdfctl/docs/man/policy/subject-condition-sets/create.md.
- The value shape is wrong. The flag takes a structured JSON array of subject sets — not a JQ-style expression string. The platform parses each subject set with
protojson.Unmarshal into a policy.SubjectSet. The shown form ('[".clientId == \"...\""]') cannot parse and otdfctl will error.
What the example should look like
Following the structure documented in the same repo's Subject Mapping Guide and verified against otdfctl/cmd/policy/subjectConditionSets.go:
otdfctl policy subject-condition-sets create \
--subject-sets '[
{
"condition_groups": [{
"boolean_operator": 1,
"conditions": [{
"subject_external_selector_value": ".clientId",
"operator": 1,
"subject_external_values": ["<your-client-id>"]
}]
}]
}
]' \
--label "My Service Account"
Impact
External developers following the SDK troubleshooting page to grant themselves entitlements will hit an otdfctl error on the first subject-condition-sets create step, with no obvious indication that the canonical guide is wrong. The Subject Mapping Guide on the same docs site has the correct syntax — fixing this snippet to point at or mirror that guide is the cleanest resolution.
Suggested fix
Replace the subject-condition-sets create block in docs/sdks/troubleshooting.mdx with the structured form above, or replace the entire mini-tutorial with a link to the Subject Mapping Guide (which already covers this flow correctly and in depth).
Summary
The
Permission Denied / Insufficient Entitlementssection indocs/sdks/troubleshooting.mdx(lines ~228-241) shows asubject-condition-sets createexample that uses an incorrect flag name and an incorrect JSON shape:otdfctl policy subject-condition-sets create \ --subject-set '[".clientId == \"<your-client-id>\""]' \ --label "My Service Account"Two problems:
--subject-sets(plural), not--subject-set. See otdfctl/docs/man/policy/subject-condition-sets/create.md.protojson.Unmarshalinto apolicy.SubjectSet. The shown form ('[".clientId == \"...\""]') cannot parse andotdfctlwill error.What the example should look like
Following the structure documented in the same repo's Subject Mapping Guide and verified against
otdfctl/cmd/policy/subjectConditionSets.go:Impact
External developers following the SDK troubleshooting page to grant themselves entitlements will hit an
otdfctlerror on the firstsubject-condition-sets createstep, with no obvious indication that the canonical guide is wrong. The Subject Mapping Guide on the same docs site has the correct syntax — fixing this snippet to point at or mirror that guide is the cleanest resolution.Suggested fix
Replace the
subject-condition-sets createblock indocs/sdks/troubleshooting.mdxwith the structured form above, or replace the entire mini-tutorial with a link to the Subject Mapping Guide (which already covers this flow correctly and in depth).