PhoenixmlDb

Troubleshooting

Common issues and solutions for storage, queries, transactions, and clusters

#Troubleshooting

Common issues and their solutions when working with PhoenixmlDb.

#Storage Issues

#"Map full" Error

Symptom: MDB_MAP_FULL: Environment mapsize limit reached

Cause: Database size exceeded configured MapSize.

Solution:

// Increase MapSize
db.Resize(currentMapSize * 2);
// Or set larger initial size
var options = new DatabaseOptions
{
    MapSize = 20L * 1024 * 1024 * 1024  // 20 GB
};
                                  

#"Max readers reached"

Symptom: MDB_READERS_FULL: Environment maxreaders limit reached

Cause: Too many concurrent read transactions.

Solution:

// Increase max readers
var options = new DatabaseOptions
{
    MaxReaders = 256
};
// Or ensure transactions are being disposed
using (var txn = db.BeginTransaction(readOnly: true))
{
    // Always dispose transactions
}
                                  

#Database Corruption

Symptom: Errors on startup, data inconsistency

Cause: Unclean shutdown, disk failure

Solution:

# Check database integrity
phoenixmldb-admin check ./data
# If corruption detected, restore from backup
phoenixmldb-admin restore ./data --from backup.tar
                                  

#"Permission denied" opening a read-only database

Symptom: LightningException: Permission denied on the first call to GetContainer, Query, or any operation that touches a named structure, when the engine was opened with ReadOnly = true.

Cause: Read-only mode cannot allocate new named databases on disk. If the directory is brand-new (or was never written to with the same set of containers/indexes the application expects), the structures don't exist and read-only mode can't create them.

Solution: Initialize the database with a writer first, then attach read-only:

using (var writer = new XmlDatabase("./data"))
{
    writer.CreateContainer("my_container");
}
using var reader = new XmlDatabase("./data", new DatabaseOptions { ReadOnly = true });
                                  

See Read-Only Mode for the full lifecycle.

#"MDB_BAD_VALSIZE" on long namespace URIs

Symptom: LightningException: MDB_BAD_VALSIZE: Unsupported size of key/DB name/data when interning a namespace URI longer than ~500 bytes.

Cause: Older versions used the URI bytes directly as the LMDB key, which is capped at 511 bytes. Resolved in current builds — the reverse namespace map now keys on a SHA-256 hash of the URI.

Solution: Upgrade to the current PhoenixmlDb release. Existing databases are migrated automatically on first open with the new build.

#Query Issues

#Slow Queries

Symptom: Queries take longer than expected

Diagnosis:

var plan = db.Explain(query);
Console.WriteLine(plan);
// Check if indexes are being used
                                  

Solutions:

1. Add appropriate indexes

2. Rewrite query to filter early

3. Limit result size

4. Use parameters instead of string concatenation

#Query Parse Errors

Symptom: XQueryParseException

Common causes:

• Missing quotes around strings

• Invalid XPath syntax

• Mismatched brackets

• Reserved word used as variable

Example fixes:

(: Wrong :)
for $x in //item where name = test return $x
(: Correct - quote the string :)
for $x in //item where name = 'test' return $x
(: Wrong :)
for $for in //item return $for
(: Correct - don't use reserved words :)
for $item in //item return $item
                                  

#Type Errors

Symptom: XPTY0004: Type error

Solution:

(: Wrong - comparing string to number :)
//product[price > '100']
(: Correct - use number :)
//product[xs:decimal(price) > 100]
                                  

#Transaction Issues

#Deadlock

Symptom: Transaction hangs or times out

Cause: Multiple transactions waiting on each other

Solution:

// Use retry pattern
public T ExecuteWithRetry<T>(Func<ITransaction, T> operation)
{
    for (int i = 0; i < 3; i++)
    {
        try
        {
            using var txn = db.BeginTransaction();
            var result = operation(txn);
            txn.Commit();
            return result;
        }
        catch (TransactionConflictException)
        {
            Thread.Sleep(100 * (i + 1));
        }
    }
    throw new Exception("Max retries exceeded");
}
                                  

#Transaction Timeout

Symptom: TransactionTimeoutException

Solution:

// Increase timeout
var options = new TransactionOptions
{
    Timeout = TimeSpan.FromMinutes(5)
};
// Or break into smaller transactions
                                  

#Write Blocked

Symptom: Write operations hang

Cause: Long-running read transaction blocking writes

Solution:

• Ensure read transactions are disposed promptly

• Use shorter transactions

• Don't hold transactions across async operations

#Connection Issues

#Cannot Connect to Server

Symptom: ConnectionRefusedException

Checklist:

1. Server is running: phoenixmldb-server status

2. Port is correct

3. Firewall allows connection

4. TLS certificate is valid

#Authentication Failed

Symptom: AuthenticationException

Checklist:

1. Username and password correct

2. User exists in server config

3. API key is valid (if using)

#TLS Errors

Symptom: SSL/TLS handshake failed

Solutions:

// Trust self-signed certificate
var options = new ClientOptions
{
    TlsSkipVerify = true  // Only for development
};
// Or specify certificate
var options = new ClientOptions
{
    TlsCaCertificate = "/path/to/ca.crt"
};
                                  

#Cluster Issues

#Split Brain

Symptom: Multiple nodes claim to be leader

Cause: Network partition with nodes unable to communicate

Solution:

1. Restore network connectivity

2. If persistent, restart minority partition

3. Check firewall rules between nodes

#Node Won't Join

Symptom: New node cannot join cluster

Checklist:

1. Cluster ID matches

2. Network connectivity to peers

3. Raft ports open

4. Configuration correct

#Replication Lag

Symptom: Followers behind leader

Diagnosis:

phoenixmldb-cluster status
# Shows replication status for each node
                                  

Solutions:

1. Check network bandwidth

2. Reduce write load

3. Increase snapshot frequency

#Performance Issues

#High Memory Usage

Causes and solutions:

1. Large transactions — Use smaller batches

2. Unclosed transactions — Ensure disposal

3. Large documents in memory — Use streaming

4. Many readers — Reduce max readers

#High CPU Usage

Causes and solutions:

1. Complex queries — Optimize or add indexes

2. Full scans — Add path/value indexes

3. XPath compilation — Use prepared queries

#High Disk I/O

Causes and solutions:

1. Frequent syncs — Consider NoMetaSync

2. Large writes — Batch in transactions

3. No SSD — Upgrade to SSD storage

#Logging and Diagnostics

#Enable Debug Logging

var options = new DatabaseOptions
{
    Logger = LoggerFactory.Create(builder =>
    {
        builder.AddConsole();
        builder.SetMinimumLevel(LogLevel.Debug);
    }).CreateLogger<XmlDatabase>()
};
                                  

#Query Metrics

var options = new QueryOptions
{
    CollectMetrics = true
};
var result = db.Query(xquery, options);
Console.WriteLine($"Parse: {result.Metrics.ParseTime}");
Console.WriteLine($"Execute: {result.Metrics.ExecuteTime}");
Console.WriteLine($"Rows scanned: {result.Metrics.RowsScanned}");
                                  

#Database Statistics

var stats = db.GetStatistics();
Console.WriteLine($"Containers: {stats.ContainerCount}");
Console.WriteLine($"Documents: {stats.DocumentCount}");
Console.WriteLine($"Size: {stats.UsedBytes / 1024 / 1024} MB");
Console.WriteLine($"Readers: {stats.ActiveReaders}");
                                  

#Getting Help

If you can't resolve an issue:

1. Check the documentation

2. Search GitHub Issues

3. Create a new issue with:

   • PhoenixmlDb version

   • .NET version

   • Operating system

   • Minimal reproduction code

   • Full error message and stack trace