Skip to main content

Troubleshooting

These are the problems people meet on a first run: a build that fails, a broker that won't start, and the first refusals. Each entry says what is wrong and links to the page that covers it in full.

Building​

  • The compiler rejects a -Z option, or says it needs nightly

    Cargo isn't using the toolchain the repository names. Build inside the checkout, with the cargo that rustup provides, and run rustup toolchain install there if the pinned nightly is missing. A cargo from another package manager ignores rust-toolchain.toml.

  • The build fails in aws-lc-sys, or asks for CMake

    The TLS library compiles native code. Install cmake and a C compiler, then build again.

Starting the broker​

  • The broker stops right after it starts, with a database error

    It couldn't connect within database.acquire_timeout. Start the database first, and check database.connection. With Docker Compose, docker compose ps should show postgresql as healthy.

  • The broker stops with loading configuration failed: and names connection

    No configuration layer names the database. Set database.connection in the file, or ANDROMEDA__DATABASE__CONNECTION in the environment. It is the one setting without a default, so the broker can't start without it.

  • The broker stops with invalid configuration:

    A setting is out of range, or two settings contradict each other. The message names them. andromeda configuration validate reports the same without starting anything, and Configuration lists every key.

  • The broker stops because its port is taken

    Another process listens on 1056 or 1086. Stop it, or move the broker with --port or management.port.

  • The log shows database_connection_capacity_exceeded at warn

    The broker's pools could hold more connections than PostgreSQL allows. The published PostgreSQL image allows 200, which fits the defaults, but a stock PostgreSQL allows 100. Raise max_connections on your server, or shrink the pools. That is harmless with a few tenants, and the Deployment planner sizes them for a real deployment.

  • Every request to a tenant gets 500 InternalError, and the log says tenant schema contract:

    The database server lacks something the schema needs, and the rest of the log line names it. It is usually a PostgreSQL, PostGIS or TimescaleDB older than the minimum, an extension the server doesn't ship, or a database encoding other than UTF-8. The published PostgreSQL image meets all of these. With a server of your own, PostgreSQL lists what the broker checks. A line about a schema version or a migrations digest means something else, which Upgrades covers.

Requests​

  • 415 with no body

    The request has no Content-Type, or one the operation doesn't take. Send application/json or application/ld+json.

  • 400 about the @context

    An application/json body can't carry a @context, and an application/ld+json body must carry one and can't also have a context Link header. JSON-LD @context has the rules.

  • 400 on a query that names nothing

    A query must narrow: a type, attrs, q, a geoquery, id or local=true. A bare GET /ngsi-ld/v1/entities is refused.

  • 400 on an id or a Relationship target

    Both must be URIs, such as urn:ngsi-ld:Building:townhall. A bare name is refused.

  • 504 LdContextNotAvailable

    The broker couldn't fetch the @context the request names. Check that its URL is reachable from the broker, or store it in the broker first, as the Quickstart does.

  • 404 or 405 on a path or method you expected

    It may belong to an extension, and extensions are off by default. With one off, its paths answer 404 and its methods 405, as if the broker had never had them. Extensions lists them.

  • 501 NoMultiTenantSupport

    The broker runs with tenancy.mode = "disabled", so it refuses any request with NGSILD-Tenant. Leave the header out, or turn tenancy on.

  • 503 with Retry-After

    A connection pool is full, or the database can't be reached. The detail says which. Store outages covers every 503.

  • 500 InternalError after a long wait

    The request ran past request_limits.timeout, 30 seconds by default. Ask for less in one request, or raise the timeout.

  • 408 RequestTimeout

    The request body hadn't fully arrived when request_limits.timeout ran out. Check that the client sends the whole body it announces in Content-Length. Over HTTP/1.1 the broker also closes the connection.

Notifications​

  • Nothing arrives at the endpoint

    Read the subscription back. timesFailed and lastFailure show whether the broker tried and failed. The endpoint must be reachable from where the broker runs, which isn't the same as your machine when the broker is in a container. Inside a container, localhost is the container itself, and the Quickstart shows how to reach your machine instead. The endpoint must also answer with a 2xx, because the broker never follows a redirect.

  • Nothing arrives, and the subscription shows no failures either

    The write didn't raise one of its triggers. By default, a subscription hears about attributes being created or updated, not deleted, and a write that changes nothing notifies nobody. Subscriptions and notifications has the rules.

Last updated on