Troubleshooting

Common issues and solutions when working with the Couchbase module.

Common issues and solutions when working with the Couchbase module.

🚨 Connection Issues

Cannot connect to Couchbase

Symptoms:

Error: Timeout during bootstrap

Solutions:

1. Verify Couchbase is running:

curl -u Administrator:password http://localhost:8091/pools

1. Check connection string:

// Single node
"connectionString": "couchbase://localhost"

// Multiple nodes
"connectionString": "couchbase://node1,node2,node3"

// Secure connection
"connectionString": "couchbases://cluster.example.com"

1. Verify credentials:

// Make sure username/password are correct
"username": "Administrator",
"password": "your_actual_password"

1. Check firewall rules:

• Port 8091: Management/REST API

• Port 8093: N1QL Query

• Port 11210: Key-Value operations

Connection timeout errors

Symptoms:

Error: connectTimeout exceeded

Solution: Increase timeout values:

this.caches["default"] = {
    "provider": "Couchbase",
    "properties": {
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "default",
        "connectTimeout": "30000", // 30 seconds
        "kvTimeout": "5000"
    }
};

🗄️ Bucket/Collection Issues

Bucket not found

Symptoms:

Error: Bucket "mybucket" not found

Solutions:

1. Verify bucket exists in Couchbase:

curl -u Administrator:password http://localhost:8091/pools/default/buckets

1. Create bucket if needed:

• Via Couchbase Web Console (http://localhost:8091)

• Or via CLI:

couchbase-cli bucket-create -c localhost:8091 \
  -u Administrator -p password \
  --bucket mybucket --bucket-type couchbase --bucket-ramsize 256

1. Check bucket name in config:

"bucket": "default" // Must match exactly (case-sensitive)

Scope or collection not found

Symptoms:

Error: Collection not found

Solution: Create scope/collection or use defaults:

// Use default scope/collection
"scope": "_default",
"collection": "_default"

// Or specify custom ones (must exist in Couchbase)
"scope": "myapp",
"collection": "sessions"

🔐 Authentication Issues

Invalid credentials

Symptoms:

Error: Authentication failed

Solutions:

1. Check username/password:

"username": "Administrator", // Case-sensitive!
"password": "password" // Check for typos

1. Verify user has permissions:

# List users
couchbase-cli user-list -c localhost:8091 -u Administrator -p password

# Grant permissions if needed
couchbase-cli user-manage -c localhost:8091 \
  -u Administrator -p password \
  --set --rbac-username myuser --rbac-password mypass \
  --roles bucket_full_access[mybucket]

1. Use environment variables for security:

"username": env("COUCHBASE_USER"),
"password": env("COUCHBASE_PASS")

📝 Query Issues

N1QL query errors

Symptoms:

Error: syntax error - at FROM

Solutions:

1. Escape bucket names with backticks:

// ❌ Wrong
query = "SELECT * FROM mybucket WHERE type = 'user'"

// ✅ Correct
query = "SELECT * FROM `mybucket` WHERE type = 'user'"

1. Use proper collection path:

// Full path format: `bucket`.`scope`.`collection`
query = "SELECT * FROM `myapp`.`_default`.`_default` WHERE ..."

1. Use parameterized queries:

couchbaseQuery(
    cacheName = "default",
    query = "SELECT * FROM `mybucket` WHERE type = $type",
    parameters = { "type": "user" }
);

Index not found

Symptoms:

Error: No index available

Solution: Create a primary index:

couchbaseQuery(
    cacheName = "default",
    query = "CREATE PRIMARY INDEX ON `mybucket`"
);

// Or create specific index
couchbaseQuery(
    cacheName = "default",
    query = "CREATE INDEX idx_type ON `mybucket`(type)"
);

🤖 Vector Search Issues

Vector search returns no results

Solutions:

1. Verify vector index exists:

// Check system:indexes
results = couchbaseQuery(
    cacheName = "default",
    query = "SELECT * FROM system:indexes WHERE name LIKE '%vector%'"
);

1. Create vector index if needed:

couchbaseQuery(
    cacheName = "default",
    query = "CREATE INDEX idx_embedding ON `mybucket`(embedding VECTOR) WHERE type = 'vector_document'"
);

1. Check embedding dimensions:

// Make sure all embeddings have same dimension
var embedding = getOpenAIEmbedding(text); // Should be 1536 for text-embedding-3-small
println("Embedding dimensions: #embedding.len()#");

1. Verify documents are stored correctly:

doc = couchbaseVectorGet(cacheName="default", id="vec_test");
println("Embedding exists: #structKeyExists(doc, 'embedding')#");
println("Embedding length: #doc.embedding.len()#");

Low similarity scores

Solutions:

1. Use same embedding model for storage and search:

// Store
storeEmbedding = getOpenAIEmbedding(text); // text-embedding-3-small

// Search - must use same model!
searchEmbedding = getOpenAIEmbedding(query); // text-embedding-3-small

1. Improve query quality:

// ❌ Too generic
query = "help"

// ✅ More specific
query = "How do I configure session storage with Couchbase?"

1. Adjust result limit:

// Get more results and filter by score
results = couchbaseVectorSearch(
    cacheName = "default",
    collection = "docs._default._default",
    embedding = embedding,
    limit = 20
);

relevant = results.filter(function(r) {
    return r.score > 0.75; // Only high confidence results
});

🗄️ Session Storage Issues

Sessions not persisting

Solutions:

1. Verify session storage is configured:

this.sessionManagement = true;
this.sessionStorage = "couchbase-sessions"; // Must match cache name!

this.caches["couchbase-sessions"] = {
    "provider": "Couchbase",
    "properties": { ... }
};

1. Check cache name matches:

// These must match!
this.sessionStorage = "my-sessions";
this.caches["my-sessions"] = { ... };

1. Verify Couchbase is accessible:

try {
    provider = couchbaseGetProvider("couchbase-sessions");
    println("Session cache connected!");
} catch (any e) {
    println("Session cache error: #e.message#");
}

⚡ Performance Issues

Slow cache operations

Solutions:

1. Check network latency:

ping couchbase-server-hostname

1. Increase connection pool:

"maxConnections": 50 // Default is lower

1. Use appropriate timeouts:

"kvTimeout": "1000", // Faster for local
"kvTimeout": "5000" // Higher for remote clusters

1. Monitor with statistics:

stats = cache("default").getStats();
println("Object Count: #stats.getObjectCount()#");
println("Cache Size: #stats.getSize()# bytes");

High memory usage

Solutions:

1. Set appropriate TTLs:

// Don't cache forever!
cache("default").set("key", value, 60); // 60 minutes

1. Use cache eviction:

// Configure in Couchbase bucket settings
// - Set bucket quota
// - Enable eviction policy

1. Clear old data:

// Regular cleanup
couchbaseQuery(
    cacheName = "default",
    query = "DELETE FROM `mybucket` WHERE createdAt < $cutoff",
    parameters = { cutoff: dateAdd("d", -30, now()) }
);

🐛 Debugging Tips

Enable debug logging

In boxlang.json:

{
    "modules": {
        "bx-couchbase": {
            "debug": true
        }
    }
}

Check Couchbase logs

# Docker
docker logs couchbase

# Native install
tail -f /opt/couchbase/var/lib/couchbase/logs/couchbase.log

Test connectivity

// Simple connectivity test
try {
    provider = couchbaseGetProvider("default");
    cluster = couchbaseGetCluster("default");
    bucket = couchbaseGetBucket("default");

    println("✅ Connection successful!");
    println("Bucket: #bucket.name()#");

    // Test write
    cache("default").set("test_key", { "test": true });

    // Test read
    result = cache("default").get("test_key");
    println("✅ Read/Write working!");

    // Cleanup
    cache("default").clear("test_key");

} catch (any e) {
    println("❌ Error: #e.message#");
    println("Detail: #e.detail#");
}

📞 Getting Help

If you're still having issues:

1. Check logs - Enable debug mode and check BoxLang and Couchbase logs

2. Verify Couchbase health - Use Web Console (http://localhost:8091)

3. Test isolation - Create minimal reproduction case

4. Community support - Post on Ortus Community

5. Professional support - Ortus Solutions Support

🔗 Useful Links

• Couchbase Server Documentation

• N1QL Query Language Reference

• BoxLang Documentation

• Community Forums