Troubleshooting

Fresh

Common Issues

Installation Fails

Node.js Version

Problem: Installation fails or CLI crashes on startup.

Cause: Node.js version is below v18.

Fix:

node --version
# If below v18, upgrade:
nvm install 18
nvm use 18
npm install -g @letta-ai/letta-code

Authentication Issues

OAuth Login Fails

Problem: Browser-based OAuth does not complete.

Possible causes:

• Browser extensions blocking popups
• Cookies cleared or blocked for auth domain
• Network proxy intercepting the callback

Fix:

1. Try a different browser
2. Disable ad blockers temporarily
3. Clear cookies for the Letta auth domain
4. Check that no VPN/proxy is interfering

Memory Not Persisting

Memory Loss Between Sessions

Problem: Agent forgets information between sessions.

Possible causes:

• Memory changes not committed in MemFS
• Using a different agent ID
• Session closed before state saved

Fix:

1. Ensure session.close() is called (or use await using)
2. Verify agent ID matches between sessions
3. Check ~/.letta/agents/<agent-id>/memory for git status
4. Run /doctor to audit memory health

Subagent Fails to Launch

Subagent Error

Problem: Custom subagent does not appear or errors on invocation.

Fix:

1. Verify the .md file is in .letta/agents/ (project) or ~/.letta/agents/ (global)
2. Check frontmatter format -- name must be lowercase, starting with a letter
3. Ensure tools field lists valid tool names or all
4. Check model availability -- the specified model must be accessible

Channel Connection Issues

Telegram/Slack Not Responding

Problem: Messages sent to bot but no response.

Fix:

1. Verify letta server --channels <platform> is running
2. Check ~/.letta/channels/accounts.json for valid tokens
3. Verify routing in ~/.letta/channels/routing.yaml
4. Confirm the agent ID in the route is correct
5. Check DM policy -- user may need pairing approval

Scheduled Tasks Not Executing

Cron Tasks Missed

Problem: Scheduled tasks do not run at expected times.

Cause: Tasks only execute while letta server is connected.

Fix:

1. Ensure letta server is running continuously
2. One-shot tasks are marked missed if 5+ minutes late
3. Maximum 50 active tasks per agent
4. Check letta cron list for task status

SDK Troubleshooting

prompt() Returns Empty

// Ensure you're awaiting the promise
const result = await prompt('query');  // Not: prompt('query')

resumeSession() Fails

// Use the agent ID, not the session ID
const session = await resumeSession(agentId);  // Not sessionId

Streaming Not Working

// Use for-await-of with stream()
for await (const chunk of session.stream('query')) {
  process.stdout.write(chunk);
}
// Not: session.stream('query').then(...)

Diagnostic Commands

Command	Purpose
letta --version	Check installed version
/doctor	Audit memory health
/memory	View current memory state
/search <query>	Search conversation history
letta cron list	Check scheduled tasks
letta channels route list	Check channel routing

Getting Help

• Discord: discord.gg/letta
• GitHub: github.com/letta-ai/letta-code
• Built-in: Agents have web browsing capabilities for looking up current docs