CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/maven-com-embabel-agent--embabel-agent-shell

Interactive Spring Shell-based command-line interface for the Embabel Agent platform, providing terminal interaction, chat sessions, and agent management commands.

Overview
Eval results
Files

troubleshooting.mddocs/

Troubleshooting

Common issues and solutions when using Embabel Agent Shell.

Installation Issues

Dependency Not Found

Problem: Maven/Gradle cannot find embabel-agent-shell dependency

Solutions:

  1. Verify repository is configured:

    <repositories>
    <repository>
        <id>embabel-repo</id>
        <url>https://your-embabel-repo-url</url>
    </repository>
</repositories>

  2. Check version number is correct: 0.3.3

  3. Clear local repository cache:

    # Maven
mvn dependency:purge-local-repository

# Gradle
./gradlew clean build --refresh-dependencies

Required Dependencies Missing

Problem: NoClassDefFoundError for Spring Shell or Embabel classes

Solutions:

  1. Ensure Spring Boot and Spring Shell are on classpath
  2. Check transitive dependencies are resolved
  3. Add explicit dependencies if needed: 
    <dependency>
    <groupId>org.springframework.shell</groupId>
    <artifactId>spring-shell-starter</artifactId>
</dependency>

Configuration Issues

Shell Not Starting

Problem: Application starts but shell is not interactive

Solutions:

  1. Verify Spring Shell is enabled:

    spring:
  shell:
    interactive:
      enabled: true

  2. Check application is not running in non-interactive mode

  3. Ensure terminal supports interactive input

  4. Review startup logs for errors

Properties Not Applied

Problem: Configuration properties in application.yaml not taking effect

Solutions:

  1. Check property prefix is correct: embabel.agent.shell

  2. Verify YAML indentation:

    embabel:
  agent:
    shell:
      lineLength: 140  # Correct indentation

  3. Check for typos in property names

  4. Ensure @EnableConfigurationProperties is present on configuration class

  5. Try properties file format:

    embabel.agent.shell.lineLength=140

Personality Not Loading

Problem: Configured personality prompt provider not appearing

Solutions:

  1. Check property value matches exactly:

    embabel:
  agent:
    logging:
      personality: starwars  # Must match exactly (lowercase)

  2. Verify message file exists in resources:

    • src/main/resources/logging/starwars.txt

  3. Check component scanning includes personality packages

  4. Review startup logs for conditional bean registration messages

  5. Ensure no other PromptProvider bean conflicts

Command Issues

Command Not Found

Problem: Shell command returns "Command not found"

Solutions:

  1. Use help command to list available commands

  2. Check command spelling and aliases:

    execute → x
blackboard → bb

  3. Verify ShellCommands component is loaded

  4. Check component scanning configuration

Chat Command Not Available

Problem: chat command not found

Solutions:

  1. Verify Chatbot bean is registered:

    @Bean
fun chatbot(): Chatbot { ... }

  2. Check @Autowired(required = false) parameter

  3. Ensure chatbot implementation is on classpath

  4. Review application context logs for chatbot bean creation

Duplicate Short Flag Error

Problem: Error when using -s flag in execute or setOptions

Solutions:

  1. This is a known issue - -s conflicts between --state and --showPlanning

  2. Use long form flags:

    # Instead of: x "task" -s
x "task" --state
x "task" --showPlanning false

  3. Cannot use both short -s flags together

Execution Issues

No Goal Found

Problem: "No goal found for intent: {intent}"

Solutions:

  1. Rephrase intent more clearly

  2. Use goals command to see available goals

  3. Use chooseGoal to test goal selection:

    chooseGoal "your intent here"

  4. Check agent platform has goals registered

  5. Try open mode: x "intent" -o

Goal Not Approved

Problem: "Goal not approved by user"

Solutions:

  1. This occurs when you type 'n' at approval prompt

  2. To approve goal, type 'y' when prompted:

    Do you approve this goal: {description}? (y/n): y

  3. Review goal description before approving

  4. Check if goal selection is correct with chooseGoal first

Process Execution Stuck

Problem: ProcessExecutionStuckException

Solutions:

  1. Enable debug mode to see where it's stuck:

    x "intent" -d

  2. Check if process is waiting for user input

  3. Review agent logs for blocking operations

  4. Try with operation delays to inspect:

    x "intent" --operationDelay

  5. Check if required tools are available

Process Waiting Exception

Problem: ProcessWaitingException thrown

Solutions:

  1. This indicates process needs user input

  2. Check for awaitable requests (forms, confirmations)

  3. Ensure terminal services is properly handling awaitables

  4. Review agent output for prompts

Output Issues

Output Not Wrapping

Problem: Long lines not wrapping in terminal

Solutions:

  1. Check line length configuration:

    embabel:
  agent:
    shell:
      lineLength: 140

  2. Verify ShellProperties is injected correctly

  3. Try different line length values

Markdown Not Rendering

Problem: Markdown displayed as plain text with symbols

Solutions:

  1. Check if content contains "#" marker for auto-detection

  2. Call markdownToConsole explicitly:

    val styled = markdownToConsole(content)

  3. Verify terminal supports ANSI escape codes

ANSI Codes Visible as Text

Problem: ANSI escape codes like \u001B[31m visible in output

Solutions:

  1. Check terminal supports ANSI codes:

    echo -e "\u001B[31mRed Text\u001B[0m"

  2. Try different terminal emulator (iTerm2, Windows Terminal, etc.)

  3. Check TERM environment variable:

    echo $TERM  # Should be xterm-256color or similar

  4. Update terminal emulator to latest version

Colors Not Displaying

Problem: No color in terminal output

Solutions:

  1. Verify terminal supports colors

  2. Check color palette is properly injected

  3. Try different personality:

    embabel:
  agent:
    logging:
      personality: starwars

  4. Test with simple ANSI output

Chat Issues

Logs Interfering with Chat

Problem: Log output mixing with chat messages

Solutions:

  1. Enable log redirection:

    embabel:
  agent:
    shell:
      redirectLogToFile: true

  2. Manually redirect logs:

    val restore = terminalServices.redirectLoggingToFile("chat", workDir)
try {
    terminalServices.chat(session)
} finally {
    restore()
}

  3. Adjust logging levels:

    logging:
  level:
    com.embabel: WARN

Chat Session Hangs

Problem: Chat becomes unresponsive

Solutions:

  1. Check for blocking operations in chat session

  2. Verify LLM service is responding

  3. Enable debug logging:

    logging:
  level:
    com.embabel.agent: DEBUG

  4. Try Ctrl+C to force exit

  5. Check network connectivity to LLM service

Unable to Exit Chat

Problem: Typing "exit" doesn't end chat session

Solutions:

  1. Try uppercase: EXIT

  2. Check for extra spaces: exit (not exit )

  3. Use Ctrl+C to force exit

  4. Review chat session exit logic

  5. Check if custom chatbot overrides exit handling

Form Handling Issues

Form Not Displaying

Problem: FormBindingRequest not showing form

Solutions:

  1. Verify TerminalServices is handling awaitable

  2. Check form has supported controls (TextField, Button)

  3. Review agent output channel

  4. Enable debug mode to see awaitable handling

Form Validation Failing

Problem: Form submission rejected with validation errors

Solutions:

  1. Check field requirements:

    • Required fields must have values
    • MaxLength limits honored
    • Pattern validation must match

  2. Review validation messages:

    TextField(
    name = "email",
    required = true,
    validationPattern = ".*@.*",
    validationMessage = "Invalid email format"
)

  3. Try without validation to isolate issue

Form Submission Cancelled

Problem: Form returns null response

Solutions:

  1. This occurs when user types 'n' at submission prompt:

    Submit form? (y/n): n

  2. To submit, type 'y'

  3. Check if agent handles null response:

    val response = terminalServices.handleAwaitable(awaitable)
if (response == null) {
    // Handle cancellation
}

Bean Injection Issues

Circular Dependency

Problem: BeanCurrentlyInCreationException with shell components

Solutions:

  1. Use constructor injection, not field injection

  2. Check for circular references in dependencies

  3. Use @Lazy annotation if necessary:

    @Component
class MyService(
    @Lazy private val shellCommands: ShellCommands
)

  4. Restructure component relationships

Bean Not Found

Problem: NoSuchBeanDefinitionException for shell components

Solutions:

  1. Verify component scanning includes embabel packages:

    @SpringBootApplication
@ComponentScan(basePackages = ["com.embabel.agent", "your.package"])
class Application

  2. Check if conditional beans match conditions

  3. Review auto-configuration imports

  4. Add explicit bean definitions if needed

Performance Issues

Slow Startup

Problem: Application takes long time to start

Solutions:

  1. Check for expensive operations in bean initialization

  2. Review auto-configuration logs

  3. Use lazy initialization:

    spring:
  main:
    lazy-initialization: true

  4. Profile startup with actuator

High Memory Usage

Problem: Application uses excessive memory

Solutions:

  1. Check for memory leaks in custom components

  2. Review blackboard size and cleanup

  3. Monitor with JVM tools:

    jmap -heap <pid>

  4. Adjust JVM memory settings:

    java -Xmx512m -Xms256m -jar app.jar

Slow Command Execution

Problem: Commands take long time to execute

Solutions:

  1. Enable debug mode to identify bottlenecks:

    x "task" -d

  2. Check LLM service latency

  3. Review tool execution times:

    toolStats

  4. Optimize agent configurations

Logging Issues

Logs Not Redirecting to File

Problem: redirectLogToFile not working

Solutions:

  1. Verify directory exists and is writable

  2. Check file permissions

  3. Review logback configuration

  4. Try manual redirection:

    val restore = terminalServices.redirectLoggingToFile("test", ".")
// ... work
restore()

  5. Check for logback.xml conflicts

Log Pattern Not Applied

Problem: Custom log pattern not working

Solutions:

  1. The redirectLoggingToFile uses fixed pattern:

    %d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n

  2. To customize, modify logback configuration

  3. Or implement custom logging redirection

Platform Issues

Windows-Specific Issues

Problem: Shell not working correctly on Windows

Solutions:

  1. Use Windows Terminal instead of CMD

  2. Enable ANSI support:

    reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

  3. Check PowerShell version

  4. Try Git Bash or WSL

macOS-Specific Issues

Problem: Terminal features not working on macOS

Solutions:

  1. Use iTerm2 for better ANSI support

  2. Check Terminal.app preferences

  3. Verify JLine native libraries

  4. Update macOS if needed

Linux-Specific Issues

Problem: Terminal features not working on Linux

Solutions:

  1. Verify TERM environment variable

  2. Check ncurses libraries installed

  3. Try different terminal emulator

  4. Review JLine native support

Getting Help

If issues persist:

  1. Check Documentation:

    • Quick Start
    • Guides
    • Reference

  2. Enable Debug Logging:

    logging:
  level:
    com.embabel.agent: DEBUG

  3. Review Stack Traces:

    • Look for root cause in exceptions
    • Check for configuration errors

  4. Test in Isolation:

    • Create minimal reproduction
    • Test with default configuration

  5. Check Dependencies:

    • Verify versions are compatible
    • Review transitive dependencies

  6. Community Support:

    • Consult Embabel documentation
    • Contact support team
    • Report bugs with reproducible examples
tessl i tessl/maven-com-embabel-agent--embabel-agent-shell@0.3.0

docs

examples.md

index.md

quickstart.md

troubleshooting.md

tile.json