pathwaycom/pathway · error · RuntimeError

milvus-lite failed to start a local server for: {uri}

Error message

milvus-lite failed to start a local server for: {uri}

What it means

For URIs ending in .db, pw.io.milvus.write uses milvus-lite's server_manager to start an embedded local server and obtain a UDS URI. If start_and_get_uri returns None — meaning milvus-lite could not bring up the local server for that path — the connector raises RuntimeError naming the URI.

Source

Thrown at python/pathway/io/milvus/__init__.py:128

    When the URI is a local ``.db`` file, pymilvus starts a milvus-lite
    server and rewrites the URI to a Unix-domain-socket path
    (``unix:/path/to/sock``).  In 2.6.x the socket address is stored in
    ``ConnectionConfig.address`` but is never forwarded to ``GrpcHandler``,
    so ``GrpcHandler._address`` ends up as an empty string and the
    connection hangs.  Passing ``address=`` as an explicit keyword argument
    causes it to flow through ``handler_kwargs`` directly into
    ``GrpcHandler.__init__``, where ``kwargs.get("address")`` picks it up.

    A freshly started local server may not be accepting connections yet, so the
    client is created through :func:`_connect_with_retry`.
    """
    if uri.endswith(".db"):
        with optional_imports("milvus"):
            from milvus_lite.server_manager import server_manager_instance

            uds_uri = server_manager_instance.start_and_get_uri(uri)
            if uds_uri is None:
                raise RuntimeError(
                    f"milvus-lite failed to start a local server for: {uri}"
                )
            return _connect_with_retry(MilvusClient, uds_uri)

    return _connect_with_retry(MilvusClient, uri)


@check_arg_types
@trace_user_frame
def write(
    table: Table,
    uri: str,
    collection_name: str,
    *,
    primary_key: ColumnReference,
    batch_size: int = 256,
    name: str | None = None,
    sort_by: Iterable[ColumnReference] | None = None,

View on GitHub (pinned to fa2f74a464)

Solutions

1. Check the directory of the .db path exists and is writable by the process
2. Delete or move the suspect existing .db file and retry — a corrupt file prevents server start
3. Verify milvus-lite supports your platform; otherwise point uri at a running Milvus server (http://localhost:19530) or use Docker
4. Reinstall the milvus package (pip install -U pymilvus) so the bundled milvus-lite binary matches your platform

Example fix

# before
pw.io.milvus.write(t, uri="./data/milvus.db", collection_name="docs", primary_key=t.id)

# after (data dir missing)
import os; os.makedirs("data", exist_ok=True)
pw.io.milvus.write(t, uri="./data/milvus.db", collection_name="docs", primary_key=t.id)

from pathlib import Path

def milvus_db_ready(uri: str) -> bool:
    if not uri.endswith(".db"):
        return True
    p = Path(uri)
    return p.parent.exists() and p.parent.is_dir() and os.access(p.parent, os.W_OK)

for attempt in range(3):
    try:
        client = _make_client(MilvusClient, uri)
        break
    except RuntimeError as e:
        if "milvus-lite failed to start" not in str(e) or attempt == 2:
            raise
        time.sleep(2 ** attempt)

When it happens

Trigger: Calling pw.io.milvus.write(table, uri='./milvus.db', ...) when milvus-lite fails to launch: unwritable directory, corrupt existing .db file, unsupported platform (milvus-lite has no builds for some OSes/architectures), or resource limits.

Common situations: First run in a container without write permission to the .db path; milvus-lite not supporting the platform (e.g. Windows natively, some ARM images); leftover corrupt database file from a crashed run.

Related errors

• Invalid schema. Time columns must be int or float.
• demo.replay_csv_with_time: unit should be either 's', 'ms, '
• Value {val} is not of type {dtype}.
• Cannot convert Json {self.value} to {type}
• no persistent storage configured for the disk cache

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/894bb4c2d2eca988. Report an issue: GitHub.