graphiti [BUG] # Official Docker Image Doesn't Support FalkorDB

Summary

The official zepai/graphiti:latest Docker image does not support FalkorDB deployment despite the documentation showing FalkorDB as a supported backend. The image only supports Neo4j and fails to start when FalkorDB environment variables are provided.

Problem Description

Expected Behavior

According to the official FalkorDB documentation at https://github.com/getzep/graphiti/blob/main/README.md, Graphiti should support FalkorDB with the following configuration:

# Install with FalkorDB support
pip install graphiti-core[falkordb]

# Environment variables
export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
export OPENAI_API_KEY=your_key

Actual Behavior

When attempting to deploy using the official Docker image zepai/graphiti:latest with FalkorDB configuration, the container fails to start with validation errors.

Steps to Reproduce

Deploy FalkorDB container (working correctly):

docker run -d --name falkordb \
  -p 6379:6379 -p 3000:3000 \
  --restart unless-stopped \
  falkordb/falkordb:latest

Create Graphiti server configuration:

# .env file
FALKORDB_HOST=host.docker.internal
FALKORDB_PORT=6379
FALKORDB_DATABASE=my_knowledge_graph
OPENAI_API_KEY=your_openai_api_key
MODEL_NAME=gpt-4o-mini
GROUP_ID=test_falkordb

Create docker-compose.yml:

version: '3.8'
services:
  graphiti-api:
    image: zepai/graphiti:latest
    ports:
      - '8000:8000'
    env_file:
      - .env

Deploy Graphiti container:
```
docker-compose up -d
```

Error Details

The container exits with code 3 and produces the following error logs:

ERROR:    Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/starlette/routing.py", line 692, in lifespan
    async with self.lifespan_context(app) as maybe_state:
  File "/usr/local/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan
    async with original_context(app) as maybe_original_state:
  File "/usr/local/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan
    async with original_context(app) as maybe_original_state:
  File "/app/graph_service/main.py", line 13, in lifespan
    settings = get_settings()
  File "/app/graph_service/config.py", line 23, in get_settings
    return Settings()
  File "/usr/local/lib/python3.12/site-packages/pydantic_settings/main.py", line 176, in __init__
    super().__init__(
  File "/usr/local/lib/python3.12/site-packages/pydantic/main.py", line 214, in __init__
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
pydantic_core._pydantic_core.ValidationError: 3 validation errors for Settings
neo4j_uri
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]
neo4j_user
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]
neo4j_password
  Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]

Root Cause Analysis

The official Docker image zepai/graphiti:latest contains server code that:

Only supports Neo4j: The Settings class in /app/graph_service/config.py requires neo4j_uri, neo4j_user, and neo4j_password fields
Doesn't support FalkorDB: No FalkorDB environment variables are recognized
Mismatch with documentation: The documentation shows FalkorDB support, but the Docker image doesn't implement it

Impact

Users cannot deploy Graphiti with FalkorDB using the official Docker image
Documentation is misleading - suggests FalkorDB support exists in Docker deployment
Requires custom builds - users must build their own Docker images to use FalkorDB
Blocks production deployments - FalkorDB users cannot use the official deployment method

Environment Information

FalkorDB Version: falkordb/falkordb:latest (FalkorDB v4.10.3 on Redis 7.4.2)
Graphiti Docker Image: zepai/graphiti:latest
Deployment Method: Docker Compose
Operating System: Ubuntu (Docker host)
Docker Version: Latest

Additional Context

This issue was discovered while following the official FalkorDB deployment instructions exactly. The FalkorDB container works perfectly, but the Graphiti API server cannot connect to it due to the missing FalkorDB support in the official Docker image.

Related Issues

This appears to be a gap between the documented FalkorDB support and the actual Docker image implementation. Users who want to use FalkorDB with Graphiti currently have no official Docker deployment option.

Priority: High - This blocks FalkorDB users from using the official deployment method Labels: bug, docker, falkordb, deployment, documentation

Jul 19 '25 21:07 omernesh

Is someone working on this already? This is a highly desired feature for rest server. Not only FalkorDB, but adding support for other LLM Providers through the usage of optional environment variables would be a fine addition, since this is already supported by Graphiti.

Jul 22 '25 14:07 luiz-native

version: '3.8' services: graphiti-api: image: zepai/graphiti:latest ports: - '8000:8000' env_file: - .env volumes: - ./beem:/path/inside/container/beem

Silly question the file was mounted eg

On Sat, 19 Jul 2025, 23:37 omernesh, @.***> wrote:

omernesh created an issue (getzep/graphiti#749) https://github.com/getzep/graphiti/issues/749 Summary

The official zepai/graphiti:latest Docker image does not support FalkorDB deployment despite the documentation showing FalkorDB as a supported backend. The image only supports Neo4j and fails to start when FalkorDB environment variables are provided. Problem Description Expected Behavior

According to the official FalkorDB documentation at https://github.com/getzep/graphiti/blob/main/README.md, Graphiti should support FalkorDB with the following configuration:

Install with FalkorDB support

pip install graphiti-core[falkordb]

Environment variablesexport FALKORDB_HOST=localhostexport FALKORDB_PORT=6379export OPENAI_API_KEY=your_key

Actual Behavior

When attempting to deploy using the official Docker image zepai/graphiti:latest with FalkorDB configuration, the container fails to start with validation errors. Steps to Reproduce

Deploy FalkorDB container (working correctly):

docker run -d --name falkordb
-p 6379:6379 -p 3000:3000
--restart unless-stopped
falkordb/falkordb:latest

Create Graphiti server configuration:

.env file

FALKORDB_HOST=host.docker.internal FALKORDB_PORT=6379 FALKORDB_DATABASE=my_knowledge_graph OPENAI_API_KEY=your_openai_api_key MODEL_NAME=gpt-4o-mini GROUP_ID=test_falkordb

Create docker-compose.yml:

version: '3.8'services: graphiti-api: image: zepai/graphiti:latest ports: - '8000:8000' env_file: - .env

Deploy Graphiti container:

docker-compose up -d

Error Details

The container exits with code 3 and produces the following error logs:

ERROR: Traceback (most recent call last): File "/usr/local/lib/python3.12/site-packages/starlette/routing.py", line 692, in lifespan async with self.lifespan_context(app) as maybe_state: File "/usr/local/lib/python3.12/contextlib.py", line 210, in aenter return await anext(self.gen) File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan async with original_context(app) as maybe_original_state: File "/usr/local/lib/python3.12/contextlib.py", line 210, in aenter return await anext(self.gen) File "/usr/local/lib/python3.12/site-packages/fastapi/routing.py", line 133, in merged_lifespan async with original_context(app) as maybe_original_state: File "/app/graph_service/main.py", line 13, in lifespan settings = get_settings() File "/app/graph_service/config.py", line 23, in get_settings return Settings() File "/usr/local/lib/python3.12/site-packages/pydantic_settings/main.py", line 176, in init super().init( File "/usr/local/lib/python3.12/site-packages/pydantic/main.py", line 214, in init validated_self = self.pydantic_validator.validate_python(data, self_instance=self) pydantic_core._pydantic_core.ValidationError: 3 validation errors for Settings neo4j_uri Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict] neo4j_user Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict] neo4j_password Field required [type=missing, input_value={'openai_api_key': 'sk-8l...el_name': 'gpt-4o-mini'}, input_type=dict]

Root Cause Analysis

The official Docker image zepai/graphiti:latest contains server code that:

Only supports Neo4j: The Settings class in /app/graph_service/config.py requires neo4j_uri, neo4j_user, and neo4j_password fields

Doesn't support FalkorDB: No FalkorDB environment variables are recognized

Mismatch with documentation: The documentation shows FalkorDB support, but the Docker image doesn't implement it

Impact

Users cannot deploy Graphiti with FalkorDB using the official Docker image

Documentation is misleading - suggests FalkorDB support exists in Docker deployment

Requires custom builds - users must build their own Docker images to use FalkorDB

Blocks production deployments - FalkorDB users cannot use the official deployment method

Suggested Solutions Option 1: Update Official Docker Image

Update the zepai/graphiti:latest image to support both Neo4j and FalkorDB backends by:

Adding FalkorDB environment variables to the Settings class

Implementing conditional logic to use FalkorDriver or Neo4jDriver based on configuration

Maintaining backward compatibility with existing Neo4j deployments

Option 2: Create FalkorDB-Specific Image

Create a separate zepai/graphiti-falkordb:latest image specifically for FalkorDB deployments. Option 3: Update Documentation

If FalkorDB support is not planned for the Docker image, update the documentation to clarify that:

FalkorDB support is only available for local Python installations

Docker deployments require Neo4j backend

Custom Docker builds are needed for FalkorDB

Environment Information

FalkorDB Version: falkordb/falkordb:latest (FalkorDB v4.10.3 on Redis 7.4.2)

Graphiti Docker Image: zepai/graphiti:latest

Deployment Method: Docker Compose

Operating System: Ubuntu (Docker host)

Docker Version: Latest

Additional Context

This issue was discovered while following the official FalkorDB deployment instructions exactly. The FalkorDB container works perfectly, but the Graphiti API server cannot connect to it due to the missing FalkorDB support in the official Docker image. Related Issues

This appears to be a gap between the documented FalkorDB support and the actual Docker image implementation. Users who want to use FalkorDB with Graphiti currently have no official Docker deployment option.

Priority: High - This blocks FalkorDB users from using the official deployment method Labels: bug, docker, falkordb, deployment, documentation

— Reply to this email directly, view it on GitHub https://github.com/getzep/graphiti/issues/749, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACUEYCKGMZEDHBQ5TUMH35T3JK3BJAVCNFSM6AAAAACB5BZRWOVHI2DSMVQWIX3LMV43ASLTON2WKOZTGI2DKNRYG43TOOI . You are receiving this because you are subscribed to this thread.Message ID: @.***>

Jul 22 '25 15:07 vvvvvvizard

version: '3.8' services: graphiti-api: image: zepai/graphiti:latest ports: - '8000:8000' env_file: - .env volumes: - ./beem:/path/inside/container/beem

Silly question the file was mounted eg …

Sorry, I'm not sure I understand what you mean. Care to elaborate? What am I doing wrong?

Jul 23 '25 20:07 omernesh

Hi @omernesh, This issue has been fixed in PR #742. We've updated the server configuration to properly support FalkorDB deployment with the official Docker image.

The validation errors you encountered will no longer occur when using FalkorDB backend.

This fix will be available once PR #742 is merged. Thanks for reporting this issue.

Jul 27 '25 07:07 Naseem77

hey, any timeline for PR #742 to be merged?

Thanks.

Aug 16 '25 22:08 omernesh

@danielchalef @prasmussen15 ?

Aug 17 '25 08:08 Naseem77

@omernesh Is this still an issue? Please confirm within 14 days or this issue will be closed.

Oct 06 '25 00:10 claude[bot]

@omernesh Is this still an issue? Please confirm within 14 days or this issue will be closed.

Nov 17 '25 00:11 claude[bot]

same question +

Dec 05 '25 14:12 leoterry-ulrica

[BUG] # Official Docker Image Doesn't Support FalkorDB - Requires Neo4j Only

Summary

Problem Description

Expected Behavior

Actual Behavior

Steps to Reproduce

Error Details

Root Cause Analysis

Impact

Suggested Solutions

Option 1: Update Official Docker Image

Option 2: Create FalkorDB-Specific Image

Option 3: Update Documentation

Environment Information

Additional Context

Related Issues

Install with FalkorDB support

Environment variablesexport FALKORDB_HOST=localhostexport FALKORDB_PORT=6379export OPENAI_API_KEY=your_key

.env file

This appears to be a gap between the documented FalkorDB support and the actual Docker image implementation. Users who want to use FalkorDB with Graphiti currently have no official Docker deployment option.