Skip to content

Troubleshooting

This section describes the first checks and common recovery procedures for AkasicDB installation, extension initialization, graph query, and vector index issues.

Collect Basic Diagnostics

First, check the PostgreSQL version, enabled extensions, current AkasicDB settings, and recent server logs. When reporting an issue, include this information along with the exact SQL statement or application error message.

SELECT version();

SELECT extname, extversion FROM pg_extension WHERE extname = 'akasicdb';

SHOW enable_graphplan;
SHOW vectoron.enable_index;
SHOW vectoron.search_mode;

If an error occurs while running the commands above, see Installation and try enabling the extension again.

You can find server logs with docker logs for Docker deployments, or in the log file specified with the pg_ctl -l option for binary deployments.

License File Is Not Found

License-related issues can occur for several reasons, such as an incorrect license file path, a missing mount, or an incorrect environment variable.

In Docker environments, mount the license directory or license file.

-v {directory-with-akasicdb_license.json}:/license
# or
-v {path-to-license-file}:/license/akasicdb_license.json

The user running the PostgreSQL process must have permission to read and write the file. An error can occur if the file is set to read-only.

In binary installation environments, check that the AKASICDB_LICENSE_PATH environment variable points to the correct license file before starting PostgreSQL.

export AKASICDB_LICENSE_PATH=$HOME/.license/akasicdb_license.json

After changing the license path or mounted directory, restart the server or container so the process can pick up the updated setting.

Extension Initialization Fails

AkasicDB must be enabled once in the database with superuser privileges.

CREATE EXTENSION IF NOT EXISTS akasicdb;

SELECT akasicdb_admin.initialize();

If this fails:

  • Check the server logs, not only the client message.
  • For binary installation environments, check that environment variables such as PATH, LD_LIBRARY_PATH, and AKASICDB_LICENSE_PATH are correct in the session that starts PostgreSQL.

Vector Query Does Not Use an Index

AkasicDB vector search uses the PostgreSQL ORDER BY ... LIMIT pattern. A query may fall back to full scan, or exact search, when no usable vector index exists or when the query planner does not choose an index.

EXPLAIN
SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;

Check the following items:

  • vectoron.enable_index is set to on.
  • The query contains both ORDER BY embedding <operator> query_vector and a LIMIT clause.
  • The operator family matches the index operator class, or opclass. For example, use vector_l2_ops with the <-> operator.
  • The query vector has the same dimension as the vector column on which the index was created.
  • The table has enough data, or rows, for the query planner to prefer an index scan.
  • idx_indexing is set to false when you need a stable benchmark after creating an index or bulk loading data.

To run exact search for a precise performance comparison, disable vector index usage in a separate session.

SET vectoron.enable_index = off;

After the comparison test, open a new session or set the value back to the original setting.

Vector Search Is Slow or Recall Is Lower Than Expected

Before changing index creation options, first tune the search parameters used at query execution time.

BEGIN;
SET LOCAL vectoron.hnsw_ef_search = 200;
SET LOCAL vectoron.vamana_l_search = 200;
SET LOCAL vectoron.ivf_nprobe = 20;

SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;
COMMIT;

Increasing the search width can improve recall, but it can also increase query latency and CPU usage. Measure performance with filter conditions, vector dimensions, and result limits that are representative of the actual service.

CREATE INDEX items_category_idx ON items (category_id);

Graph Query Fails or Returns Unexpected Results

For graph queries, first check that the graph preparation process completed correctly. After creating the graph definition, you must run the akasicdb.create_graph(...) function before an actually usable graph is created.

Before running the akasicdb.create_graph(...) function, all required vertex and edge definitions must be configured in the graph.

If a graph query fails, check the following items:

  • The graph name passed to akasicdb.cypher() matches the actual graph definition.
  • Vertex and edge definitions were created before running akasicdb.create_graph(...).
  • The akasicdb.cypher() call includes an AS clause that specifies the output column names and SQL types.
  • The GQL query string is correctly dollar-quoted with $$. Using single quotes causes an error.
  • akasicdb.cypher() must be called in the FROM clause (queries like SELECT akasicdb.cypher(...) do not work).

If the graph to be queried exists properly and you are using akasicdb.cypher() correctly, check the Notes on Using SQL/GQL section for any syntax constraints or differences from standard openCypher that may apply to your query.