@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
ts 133 lines 5.92 KB
Raw
1 import type { ReferenceDocument } from '../reference-schema';
2
3 export const troubleshootingReference: ReferenceDocument = {
4 slug: 'troubleshooting',
5 title: 'Troubleshooting',
6 intro: ['Load this file when the user is stuck on top-level Composio CLI flows.'],
7 sections: [
8 {
9 title: 'Not Logged In',
10 body: [
11 'Symptoms:',
12 '- `composio` commands fail because there is no user session',
13 '- the user is unsure which account the CLI is using',
14 'Fix:',
15 'If `composio whoami` fails, run `composio login` and then return to the original `execute` or `search` flow.',
16 ],
17 commands: [{ code: 'composio whoami' }],
18 },
19 {
20 title: 'No Active Connection Found',
21 body: [
22 'Symptoms:',
23 '- `execute` reports that no active connection exists for a toolkit',
24 'Fix:',
25 'After linking, retry the exact same `execute` command.',
26 ],
27 commands: [
28 {
29 code: 'composio link gmail --no-browser --no-wait\ncomposio link googlecalendar --no-browser --no-wait',
30 },
31 ],
32 },
33 {
34 title: 'A Command Failed And Might Work If Run Again',
35 body: [
36 'Symptoms:',
37 '- a command exits 75 instead of 1',
38 '- a failed `execute` result on stdout has a `retry` field',
39 'Fix:',
40 '- Exit 75 means the failure was temporary (rate limited, a timeout or a server error on a request that changes nothing) and running the same command again cannot act twice. Wait a few seconds and run it again; stop after two or three attempts and report the error.',
41 '- `"retry": "safe"` on a failed `execute` result means the same, and the command exits 75.',
42 '- `"retry": "check-first"` means the request failed in flight and the tool may already have run. Running it again could act twice (send the email twice, create two issues). First check whether it took effect, for example by reading the sent folder or listing the issues with another `execute`, and run it again only if it did not.',
43 '- Any other failure exits 1: running the same command again fails the same way, so fix the cause the error names.',
44 ],
45 },
46 {
47 title: 'Invalid JSON Input',
48 body: [
49 'Symptoms:',
50 '- `execute` rejects `-d` input',
51 '- the payload is not valid JSON or JS-style object syntax',
52 'Fix:',
53 '- Pass JSON or a JS-style object literal to `-d`',
54 '- Use `@file` for large payloads',
55 '- Use `-` to read from stdin',
56 'Examples:',
57 ],
58 commands: [
59 {
60 code: `composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{"owner":"acme","repo":"app","title":"Bug report","body":"Steps to reproduce..."}'
61 composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'
62 composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d @payload.json
63 cat payload.json | composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d -`,
64 },
65 ],
66 },
67 {
68 title: 'Unknown Or Wrong Slug',
69 body: [
70 'Symptoms:',
71 '- the user does not know the tool slug',
72 '- the slug exists but is not the right tool for the job',
73 'Fix:',
74 'Use multiple queries in one `search` call when the user is exploring several related tasks at once. Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.',
75 ],
76 commands: [
77 {
78 code: 'composio search "create a github issue"\ncomposio search "send an email" --toolkits gmail\ncomposio search "send an email" "create a github issue"',
79 },
80 ],
81 },
82 {
83 title: 'Confusion About Required Inputs',
84 body: [
85 'Symptoms:',
86 '- the user is unsure what fields a tool accepts',
87 '- the first payload attempt failed validation',
88 'Fix:',
89 'Use `composio tools info <slug>` only when the user wants a compact summary of a known slug and the `execute --get-schema` output is still not enough.',
90 ],
91 commands: [
92 {
93 code: `composio execute GITHUB_CREATE_AN_ISSUE --get-schema -d '{}'\ncomposio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'`,
94 },
95 ],
96 },
97 {
98 title: 'Several Independent Tool Calls',
99 body: [
100 'Symptoms:',
101 '- the user wants to run multiple unrelated tools in one step',
102 '- the user is about to write a script only to execute a few independent calls',
103 'Fix:',
104 'Escalate to `composio run` only when the user needs control flow, loops, `Promise.all`, `search()` inside a script, or `proxy()`.',
105 ],
106 commands: [
107 {
108 code: `composio execute --parallel \\\n GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \\\n GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'`,
109 },
110 ],
111 },
112 {
113 title: '`tools info` And `tools list` Are Fallbacks',
114 body: [
115 'Treat these commands as secondary inspection tools:',
116 'Do not lead with them when `execute`, `search`, `--get-schema`, or `--dry-run` can get the user unstuck faster.',
117 ],
118 commands: [{ code: 'composio tools info GMAIL_SEND_EMAIL\ncomposio tools list gmail' }],
119 },
120 {
121 title: 'Consumer Vs `composio dev`',
122 body: [
123 'Use the top-level commands for normal end-user flows:',
124 '- `composio execute`',
125 '- `composio search`',
126 '- `composio link`',
127 '- `composio run`',
128 '- `composio proxy`',
129 'Load [composio-dev.md](composio-dev.md) only when the user explicitly needs developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects.',
130 ],
131 },
132 ],
133 };