1. Introduction
  2. Reproducing the Error
  3. Issue Categories
    1. Invalid SDK Usage
    2. Missing API Key
    3. Failure Running Serve
    4. Web UI Errors
    5. Gateway Error
    6. Internal Server Error
  4. Reporting Issues


This guide provides a step-by-step approach to debugging common issues you might face while using Agenta.

Reproducing the Error

Before you start debugging, we need to determine the type of issue we are facing. For this try to reproduce the error in CLI. This will help you understand the source of the problem.

cd folder_of_your_app
python app.py <yourinputs>

If an error message appears, this means the issue is in your code.

If it works, then try serving the application

agenta variant serve --file_name <yourapp.py>

If this does not work, then the issue is in the serving process.

If it works, then the issue is in the web UI.

Issue Categories

Invalid SDK Usage

If the app dies with an error message when run from CLI, make sure to check the following:

  • Does an app.py file exist in your directory?
  • Did you use the @post decorator in your code?
  • Did you specify types for all the inputs in the function you’re calling?
  • Did you provide only str types as inputs?

Your main function should look like this:

default_prompt = "Give me five cool names for a baby from this country {{country}} with this gender {{gender}}!!!!"

def func_name(input1:str, input2:str, some_parameter: TextParam = default_prompt) -> str:
    # your code here
    return "some string"

Missing API Key

If the error message suggests an issue with the API key, try the following steps:

  1. Export the keys to your environment and run the code:
export OPENAI_API_KEY=<your key>
python app.py <yourinputs>
  1. If the code runs successfully, check if a .env file exists in the directory and if it includes the keys.
  2. Make sure to manually set the OpenAI key in your code:
def generate(country: str, gender: str, temperature: FloatParam = 0.9, prompt_template: TextParam = default_prompt) -> str:
    openai.api_key = os.environ.get("OPENAI_API_KEY")  # make sure to set this manually!
    chat_completion = openai.ChatCompletion.create(
        model="gpt-3.5-turbo", messages=[{"role": "user", "content": prompt}])

Remember to print the key to ensure it loads correctly.

Failure Running Serve

If you run agenta variant serve and it doesn’t work, follow these steps:

  1. Confirm that Docker is running.
  2. Ensure you have the latest SDK version. You can upgrade it by running pip install agenta --upgrade.
  3. Restart and rebuild Docker Compose:
docker-compose down
docker-compose up --build

If the issue persists after following these steps, try shutting down all the containers with the same name of the variant and removing all related images. If the problem continues, please report the issue or contact us directly.

Web UI Errors

If the application runs correctly in the CLI and seems to serve correctly, but you can’t run it from the web UI, please:

  1. Check if the Docker container is running.
  2. Verify if the API is running by checking if http://localhost/{app_name}/{variant_name}/openapi.json exists.
  3. If the API isn’t running, the issue might be with the reverse proxy (Traefik). To check, visit localhost:8080.
  4. If you are getting failed to load variants and in the console you see a cors error similar to the one below, try accessing the web UI using localhost instead of
apps:1 Access to fetch at 'http://localhost/api/app_variant/list_apps/' from origin '' has been blocked by CORS policy: The request client is not a secure context and the resource is in more-private address space `local`.
AppSelector.tsx:7     GET http://localhost/api/app_variant/list_apps/ net::ERR_FAILED

If none of these checks solve the problem, there might be an issue with the web UI. Please report it or contact us directly.

Gateway Error

When accessing the backend server, you may encounter a “502 Bad Gateway” error. One possible cause of this issue is that an application is running on the default backend server port (8000), resulting in the gateway error. .

To resolve this issue:

  1. Verify Traefik Configuration: check the Traefik configuration to confirm that it is correctly forwarding requests to the backend server on the /api route. Verify that the relevant Traefik rule in the docker-compose.yml file is properly configured.

  2. Prune Docker Resources: kindly follow the commands below to stop and remove all the agenta containers; and to finally prune all the volumes associated with it.

docker stop $(docker ps -q -f "name=agenta-*")
docker rm $(docker ps -aq -f "name=agenta-*")
docker volume ls -q -f "name=agenta-*"
docker volume rm VOLUME_NAME

Once you have completed these steps, start the application again by running docker compose up and access the backend server by making requests to http://localhost:8000. If the issue persists after following these troubleshooting steps, it’s essential to investigate further into the Traefik configuration and the interaction between Traefik and the backend server.

Internal Server Error

  1. If you are running agenta locally, check the container log of the App. If you are getting the error below in the docker container, check your code to make sure the output you are returning is a string.
    raise ValidationError(errors, field.type_)
pydantic.error_wrappers.ValidationError: <unprintable ValidationError object>

Reporting Issues

If you can’t solve your problem using this guide, don’t worry. We’re here to help! Please create a new issue in our repository and we will get back to you asap.

Was this page helpful?