# How to Troubleshoot CocoIndex Connector Errors: 6 Common Issues and Fixes

> Troubleshoot CocoIndex connector errors with this guide. Resolve invalid identifiers, missing schemas, and network issues to keep your indexing running smoothly.

- Repository: [CocoIndex/cocoindex](https://github.com/cocoindex-io/cocoindex)
- Tags: how-to-guide
- Published: 2026-05-05

---

**Most CocoIndex connector errors stem from invalid identifiers, missing vector schemas, unloaded extensions, or network misconfigurations, and surface as Python `ValueError` or `RuntimeError` exceptions with specific validation messages.**

CocoIndex connectors are thin, async-first adapters that translate **CocoIndex target definitions** into concrete operations on external systems like PostgreSQL, SQLite, and Neo4j. When you troubleshoot CocoIndex connector errors, you are typically tracing Python exceptions raised during validation, schema creation, or extension loading in the cocoindex-io/cocoindex repository.

## 1. Fix Invalid Identifier Validation Errors

Many connectors including `surrealdb`, `neo4j`, `falkordb`, and `doris` enforce strict naming conventions through the `_validate_identifier` helper function. This validation raises a **`ValueError`** when table names, column names, or graph identifiers contain illegal characters or empty strings.

In [`cocoindex/connectors/surrealdb/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/surrealdb/_target.py) at line 74, the validation logic explicitly checks identifier patterns:

```python
def _validate_identifier(name: str, kind: str) -> None:
    # raises ValueError on empty or malformed identifiers

```

**Common symptoms and fixes:**

- **`ValueError: Invalid SurrealDB table name …`** occurs when names contain spaces or start with digits. Verify strings passed to `declare_table` or `declare_row` match the regex `[A-Za-z_][A-Za-z0-9_]*`.
- **`ValueError: column name … is invalid`** indicates prohibited characters like hyphens. Ensure column names use only alphanumeric characters and underscores.

## 2. Resolve Vector Schema and Extension Errors

Connectors supporting vector search (`postgres`, `sqlite`, `doris`) require explicit **`VectorSchemaProvider`** definitions for NumPy `ndarray` types. Additionally, SQLite requires the optional **`sqlite-vec`** extension for vector operations.

In [`cocoindex/connectors/postgres/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/postgres/_target.py) (lines 11, 850-860), the `_get_type_mapping` function validates vector specifications:

```python

# Raises ValueError when NumPy array lacks VectorSchema or has invalid dimensions

```

For SQLite, [`cocoindex/connectors/sqlite/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/sqlite/_target.py) (lines 46-53) contains the `_create_table` method which raises **`RuntimeError`** when vector columns exist but the extension is missing.

**Troubleshooting checklist:**

| Symptom | Root Cause | Solution |
|---------|------------|----------|
| `ValueError: VectorSpecProvider is required for NumPy ndarray type.` | Missing `VectorSchema` for ndarray columns | Supply `vector_schema=VectorSchema(size=384, dtype=np.float32)` in table declarations |
| `RuntimeError: sqlite-vec extension required for vec0 virtual tables` | Extension not loaded | Call `coco.connect(..., load_vec=True)` or manually load `vec0` |
| `ValueError: Invalid pgvector dimension: 0` | Zero or negative vector size | Ensure `VectorSchema.size` is a positive integer |

## 3. Correct Primary Key and Column Definition Mismatches

Connectors validate that every primary key column exists in the declared schema. Missing keys trigger **`ValueError`** during `TableSchema` construction.

As implemented in [`cocoindex/connectors/sqlite/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/sqlite/_target.py) (lines 13-18):

```python
if pk not in self.columns:
    raise ValueError(f"Primary key column '{pk}' not found ...")

```

Fix primary key errors by ensuring all entries in `primary_key=['id']` have corresponding `ColumnDef` declarations, or correct typos in column names.

## 4. Handle Extension Loading Failures

SQLite and Doris connectors depend on optional native extensions (`sqlite-vec`, `doris-udf`). If these binaries (`.so` or `.dll`) are unavailable, the connector raises **`RuntimeError`**.

Verify extension availability before running pipelines:

```python
import sqlite3

def assert_vec_loaded(conn: sqlite3.Connection) -> None:
    conn.enable_load_extension(True)
    try:
        conn.load_extension("vec0")
    except sqlite3.OperationalError as exc:
        raise RuntimeError("sqlite-vec extension missing") from exc

# Test connection

conn = sqlite3.connect(":memory:")
assert_vec_loaded(conn)

```

To enable automatic loading in CocoIndex, use the connector's `load_extension` flags:

```python
import cocoindex as coco
from cocoindex.connectors import sqlite

env = coco.Environment(
    connect=lambda: sqlite.connect("my.db", load_vec=True)
)

```

## 5. Diagnose Network and Authentication Failures

Remote connectors (PostgreSQL, Neo4j, Kafka, Qdrant) propagate underlying library exceptions directly without wrapping. You will see original stack traces from `asyncpg`, `neo4j-python-driver`, or `aiohttp`.

**Common connection errors:**

- **`asyncpg.exceptions.InvalidPasswordError`**: Verify `dsn`, `user`, and `password` parameters in `coco.connect`.
- **`ConnectionRefusedError` from Kafka**: Check broker addresses, firewall rules, and TLS settings.
- **`aiohttp.ClientConnectorError` from Qdrant**: Confirm the HTTP endpoint URL and port configuration.

## Code Examples for Common Fixes

### Catching Identifier Errors in SurrealDB

```python
import cocoindex as coco
from cocoindex.connectors import surrealdb

try:
    target = await coco.use_mount(
        surrealdb.declare_table,
        "my table",               # ← illegal space

        columns={"id": int, "name": str},
    )
except ValueError as e:
    # e.g., "Invalid SurrealDB table name: my table"

    print("Fix the name:", e)

```

### Enabling sqlite-vec for Vector Tables

```python
import cocoindex as coco
from cocoindex.connectors import sqlite
import numpy as np

# Load the sqlite-vec extension automatically

env = coco.Environment(
    connect=lambda: sqlite.connect("my.db", load_vec=True)   # <- important

)

# Declare a table with a vector column

await env.use_mount(
    sqlite.declare_table,
    "embeddings",
    columns={
        "id": int,
        "vector": np.ndarray,            # vector column

    },
    vector_schema=coco.vector_schema(384, dtype=np.float32),
)

```

### Handling Missing PostgreSQL Vector Schema

```python
import cocoindex as coco
from cocoindex.connectors import postgres
import numpy as np

try:
    await coco.use_mount(
        postgres.declare_table,
        "items",
        columns={"id": int, "embedding": np.ndarray},
        # OOPS: forgetting vector_schema argument

    )
except ValueError as e:
    # "VectorSpecProvider is required for NumPy ndarray type."

    print("Add vector_schema:", e)

```

## Summary

- **Identifier validation** in connectors like SurrealDB and Neo4j raises `ValueError` for names containing spaces or special characters.
- **Vector columns** require explicit `VectorSchema` providers and, for SQLite, the `sqlite-vec` extension loaded via `load_vec=True`.
- **Primary key constraints** must reference existing columns in the schema definition.
- **Native extensions** must be present in the runtime environment and explicitly enabled.
- **Network errors** pass through from underlying drivers—check credentials and connectivity directly.

## Frequently Asked Questions

### Why does CocoIndex raise "VectorSpecProvider is required" when using NumPy arrays?

This error occurs in [`cocoindex/connectors/postgres/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/postgres/_target.py) when you declare a column as `np.ndarray` without providing a `vector_schema` parameter. The connector requires explicit dimension and dtype specifications to map the array to database vector types like pgvector. Add `vector_schema=VectorSchema(size=384, dtype=np.float32)` to your table declaration.

### How do I fix "sqlite-vec extension required" errors in SQLite?

The `RuntimeError` originates from [`cocoindex/connectors/sqlite/_target.py`](https://github.com/cocoindex-io/cocoindex/blob/main/cocoindex/connectors/sqlite/_target.py) lines 46-53 when creating virtual tables with vector columns. Install the `sqlite-vec` extension binary for your platform, then enable it by passing `load_vec=True` to the SQLite connection: `sqlite.connect("db.sqlite", load_vec=True)`.

### What causes "Primary key column not found" validation errors?

This `ValueError` fires during `TableSchema` construction when your `primary_key` list references a column name not present in the `columns` dictionary. Verify that every primary key string exactly matches a key in your column definitions, including case sensitivity.

### Are network authentication errors wrapped by CocoIndex connectors?

No. Connectors for PostgreSQL, Neo4j, and Qdrant propagate native library exceptions such as `asyncpg.exceptions.InvalidPasswordError` or `aiohttp.ClientConnectorError` directly. Troubleshoot these by testing connections with the underlying driver outside of CocoIndex first.