Neo4j connection timeout failure in VS Code extension

[rysweet]

Problem

The Blarify VS Code extension is experiencing critical Neo4j connection failures with multiple concurrent connection attempts and eventual timeout after 60 seconds.

Error Details

[Neo4j ERROR] Failed to start Neo4j container
[Neo4j] Container manager start failed: Neo4j failed to start within 60000ms
[Neo4j] Error details: Error: Neo4j failed to start within 60000ms
    at Neo4jContainerManager.waitForNeo4j (/Users/ryan/.vscode-insiders/extensions/blarify.blarify-visualizer-0.1.0/bundled/neo4j-container-manager/container-manager.js:275:15)
    at Neo4jContainerManager.reuseExistingContainer (/Users/ryan/.vscode-insiders/extensions/blarify.blarify-visualizer-0.1.0/bundled/neo4j-container-manager/container-manager.js:214:9)
    at Neo4jContainerManager.start (/Users/ryan/.vscode-insiders/extensions/blarify.blarify-visualizer-0.1.0/bundled/neo4j-container-manager/container-manager.js:56:34)

Symptoms

1. Multiple concurrent connection attempts: The logs show the container manager being called 3 times simultaneously
2. Successful connections ignored: Two attempts return successfully (24390ms and 37073ms) but a third attempt times out at 60000ms
3. Container actually running: The container ID 2d283cf877e9254ac2943210555480458d1592cd588c93f5b7e4bed333cd2225 is running on port 7957
4. Subsequent checks show healthy: After the timeout error, status checks report "Existing instance is healthy"

Root Cause Analysis

The issue appears to be:

• Multiple concurrent calls to ensureRunning() during extension activation
• Race condition where multiple connection attempts overlap
• The 60-second timeout fires even though the container started successfully in ~24-37 seconds
• No proper synchronization/locking mechanism to prevent concurrent initialization

Impact

• Extension fails to initialize properly
• User sees error messages despite Neo4j actually running
• Poor user experience with unreliable startup
• Blocks core functionality of the Blarify extension

Expected Behavior

• Single connection attempt during startup
• Proper synchronization to prevent race conditions
• Recognition of successful container start regardless of timeout
• Reliable, consistent Neo4j initialization

Environment

• VS Code Insiders
• Extension version: 0.1.0
• Neo4j container manager bundled with extension
• macOS (Darwin)

Priority

CRITICAL - This is a core reliability issue that affects all users and makes the extension appear broken even when Neo4j is actually running successfully.

[rysweet]

Root Cause Analysis Update

After further investigation, the issue is NOT with the container manager - it's already designed to handle singleton connections. The real problem is:

The VS Code extension is calling Neo4jManager.ensureRunning() multiple times concurrently during activation.

Looking at the logs:

• The container manager is called 3 times simultaneously
• Each call properly goes through the container manager
• Two calls succeed (24s and 37s), but a third times out at 60s
• The container manager is working correctly - it's reusing the existing container

The Real Issue

The problem is in the extension activation logic that's triggering multiple concurrent calls to:

await neo4jManager.ensureRunning()

This is likely happening from:

1. Multiple event handlers firing during activation
2. Multiple workspace folders triggering separate ingestions
3. Configuration change handlers firing during startup

Corrected Fix Plan

1. Add initialization guard in extension.js

   • Single promise to track Neo4j initialization
   • All callers await the same promise

2. Debounce extension activation triggers

   • Prevent multiple rapid calls during startup

3. Fix the calling code, not the container manager

   • The container manager is working as designed
   • The issue is multiple concurrent calls from the extension layer

[rysweet]

Fix Implemented

I've implemented a singleton pattern to prevent concurrent Neo4j initialization calls. The fix includes:

Changes Made:

1. Added singleton promise tracking in extension.ts:

   // Neo4j initialization promise to prevent concurrent calls
   let neo4jInitPromise: Promise<void> | null = null;

2. Created ensureNeo4jRunning() helper function:

   • Returns existing promise if already initializing
   • Creates new promise only if not already running
   • Resets promise on failure to allow retry
   • Adds detailed logging with [Neo4j Singleton] prefix

3. Updated all neo4jManager.ensureRunning() calls to use the singleton:

   • Line 140: Initial setup during extension activation
   • Line 367: Before workspace ingestion
   • Line 464: During Neo4j restart (with promise reset)

How it Works:

• First call creates the initialization promise
• Subsequent concurrent calls return the same promise
• All callers await the same initialization result
• On failure, promise is reset to allow retry
• On restart, promise is explicitly reset

Testing:

The fix has been compiled and is ready for testing. The extension should now:

• Only attempt one Neo4j connection at a time
• Log [Neo4j Singleton] messages showing when promises are reused
• Prevent the timeout error from concurrent attempts

Please test the updated extension to verify the fix resolves the connection issues.

[rysweet]

✅ Fix Verified - Singleton Pattern Working

The singleton pattern fix has been successfully tested and verified to resolve the concurrent initialization issue.

Test Results:

1. No more concurrent calls: The extension no longer makes multiple simultaneous calls to Neo4j initialization
2. No timeout errors: Neo4j starts successfully without the 60-second timeout error
3. Reliable startup: The extension shows "Neo4j ready" status reliably

What the Fix Does:

• Singleton Promise Pattern: All calls to ensureNeo4jRunning() now share the same initialization promise
• Prevents Race Conditions: Multiple components can safely call the initialization without conflicts
• Proper Error Recovery: Failed attempts reset the promise to allow retries

Code Changes Summary:

1. Added neo4jInitPromise variable to track initialization state
2. Created ensureNeo4jRunning() wrapper function with singleton logic
3. Updated all neo4jManager.ensureRunning() calls to use the wrapper

The fix ensures Neo4j connections work reliably "behind the scenes" as required, eliminating the frustrating timeout errors users were experiencing.

Ready for Production

The fix has been:

• ✅ Implemented in TypeScript
• ✅ Compiled to JavaScript
• ✅ Packaged into VSIX
• ✅ Tested in clean VS Code environment
• ✅ Verified to resolve the issue

This issue can be closed once the fix is merged and released.