Troubleshooting Bob Shell

Error: Unable to verify certificate

Cause: You are on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This requires a custom root CA certificate to be trusted by Node.js.

Solution: Set the NODE_EXTRA_CA_CERTS environment variable to the absolute path of your corporate root CA certificate file:

Error: Bob Shell cannot connect to the IDE.

Cause: The Bob Shell Companion extension might not be installed or running, or Bob Shell might be running outside the workspace directory.

Solution:

1. Install the Bob Shell Companion extension in your IDE.
2. Navigate to your workspace directory in the terminal.
3. Start Bob Shell from the workspace directory.
4. Run /ide enable in Bob Shell.

Error: Bob Shell cannot connect to the IDE when running inside a dev container.

Cause: The Bob Shell port is not forwarded from the dev container to the host machine.

Solution:

1. Get the Bob Shell port from the terminal inside the dev container:

   echo $BOB_SHELL_CLI_IDE_SERVER_PORT

   Example output: 42991

2. Open the Command Palette in your IDE and select Forward a Port.

3. Add the port shown in step 1 (for example, 42991).

4. Start Bob Shell:

   bob

5. Enable IDE integration:

   /ide enable

   Or check the connection status:

   /ide status

Error: 🔴 Disconnected: Failed to connect to IDE companion extension

Cause: The Bob Shell Companion extension is not installed, not enabled, or not running in your IDE.

Solution:

1. Verify the Bob Shell Companion extension is installed and enabled in your IDE.
2. Open a new terminal in your IDE.
3. Run /ide enable in Bob Shell.

Error: 🔴 Disconnected: IDE connection error. The connection was lost unexpectedly

Cause: The IDE connection was interrupted due to a network issue or IDE restart.

Solution:

1. Run /ide enable to reconnect.
2. If the issue persists, restart your IDE.

Error: 🔴 Disconnected: Directory mismatch

Cause: Bob Shell is running in a different directory than the workspace open in your IDE.

Solution:

1. Navigate to the same directory that's open in your IDE.
2. Restart Bob Shell from that directory.

Error: 🔴 Disconnected: To use this feature, please open a workspace folder

Cause: No folder or workspace is open in your IDE.

Solution:

1. Open a folder or workspace in your IDE.
2. Restart Bob Shell.

Error: IDE integration is not supported in your current environment

Cause: Bob Shell is not running from within a supported IDE's integrated terminal.

Solution: Run Bob Shell from within a supported IDE's integrated terminal.

Error: Bob Shell ignores files you want it to access, or accesses files you want it to ignore.

Cause: The .bobignore file might have conflicting patterns, incorrect pattern order, or be in the wrong location. Changes might not have taken effect yet.

Solution:

1. Check your .bobignore file for conflicting patterns.
2. Ensure more specific patterns (like negations with !) come after general patterns.
3. Restart your Bob Shell session after making changes to .bobignore.
4. Use absolute paths if relative paths aren't working as expected.
5. Verify the .bobignore file is in your project root directory.

Error: Bob Shell settings changes do not take effect.

Cause: The settings file might be in the wrong location, have invalid JSON syntax, or be overridden by higher-priority configuration sources. Changes might not have taken effect yet.

Solution:

1. Check the settings file location:

   • Project settings: .bob/settings.json in your project directory
   • User settings: ~/.bob/settings.json in your home directory

2. Verify the JSON syntax is valid (use a JSON validator).

3. Remember the configuration precedence order:

   • Command-line arguments (highest priority)
   • Environment variables
   • Project settings
   • User settings
   • System defaults (lowest priority)

4. Restart Bob Shell after changing settings files.

Error: Custom instructions are not being applied to Bob Shell sessions.

Cause: Custom instruction files might be in the wrong location, have incorrect file extensions, or not be loaded into the current context.

Solution:

1. Verify files are in the correct location:

   • Workspace-wide: .bob/rules/ in your project root
   • Mode-specific: .bob/rules-{modeSlug}/ in your project root

2. Check that files have the correct extensions (.md, .txt, or .xml).

3. Use /memory refresh to reload all context files.

4. Use /memory show to verify the current context.

Error: command not found: bob

Cause: Bob Shell is not correctly installed or not in your system's PATH.

Solution:

1. Verify Bob Shell is installed:

   which bob

2. If not found, reinstall Bob Shell using the installation instructions.

3. Check that your shell's PATH includes the Bob Shell installation directory.

Error: Shell mode (! command) does not run commands.

Cause: You might not be typing ! at an empty prompt, lack necessary permissions, or the command itself might be invalid.

Solution:

1. Verify you're typing ! at an empty prompt.
2. Check that you have the necessary permissions to run shell commands.
3. Try running the command directly in your terminal first to verify it works.

Error: Bob Shell responds slowly to requests.

Cause: Network connectivity issues, too many files loaded as context, or large binary files included in the context.

Solution:

1. Check your network connection.
2. Reduce the number of files in context by using .bobignore.
3. Avoid including large binary files or directories like node_modules/.
4. Consider using more specific file references with @ instead of loading all files.

Error: Bob Shell consumes excessive memory.

Cause: Too many files loaded as context, large directories not excluded, or circular imports in memory files.

Solution:

1. Limit the number of files loaded as context.
2. Use .bobignore to exclude large directories.
3. Restart Bob Shell periodically during long sessions.
4. Check for circular imports in your memory files.

To see detailed logging information, start Bob Shell with the debug flag:

Or set the debug flag in your settings:

Run the following command to see your version of Bob Shell:

Interactive session:

Non-interactive session:

Check Bob Shell logs for error messages:

• Logs are typically stored in ~/.bob/logs/
• Look for recent error messages or stack traces
• Share relevant log excerpts when reporting issues