The compiled extension is missing from the Python environment running your script. Check that your terminal, editor or notebook uses the environment where you installed pyaviso. See Install.

For a source checkout, run the build commands under From source. The dev group supplies maturin, which builds the extension. If the build fails, check the Rust and C compiler requirements there. Reinstalling into a different environment will not fix the one your notebook uses.

Pass the complete URL supplied by your operator, including https:// or http:// and any required port. A hostname alone, such as localhost, is not a complete URL. The Python constructor requires base_url; the examples read it from os.environ["AVISO_BASE_URL"]. A KeyError for that name means the environment variable is missing before the client is even constructed.

See Set the environment.

Env() requires credentials. Set AVISO_TOKEN, or unset it and set both AVISO_USERNAME and AVISO_PASSWORD. A non-empty token takes precedence. For an anonymous server, pass auth=pyaviso.Anonymous(). Omitting auth does not mean anonymous: the client then searches for a credential.

A 401 means the server did not accept the request’s credentials. A 403 can mean the credentials lack permission for the operation or event type. Ask your operator to check receiving or publishing access as appropriate. Listing schemas does not prove those permissions.

ConfigFile expects an auth-only file with one top-level bearer or basic section, not a general CLI config. Env caches credentials at construction; ConfigFile rereads its file on a requested refresh after 401. See Authentication for the exact shapes and retry behavior.

Check the URL, network access and server availability. The exception message can identify a DNS, TCP or certificate problem. For TLS, check the hostname and trusted certificate chain with your operator. Disabling certificate validation is not a fix for a production certificate problem.

A transport error can also occur while receiving a response. It does not prove the server stored nothing. Check before retrying a publish to avoid duplicates. See Error handling.

A fresh listener waits for new notifications. Silence can be normal. Confirm the event type and filter against the server’s schema. In the example mars schema, class=od excludes rd; omitting step selects all steps.

Use replay-only mode to read retained history once and exit. start_from=0 requests retained history after sequence zero. It cannot restore expired records. You do not need to publish anything yourself.

Inspect reason. replay_limit_reached means the server capped the requested replay; max_allowed reports the cap. It does not by itself mean all missing records expired. sequence_jump reports an unexpected protocol sequence boundary through expected and observed.

The iterator stops rather than silently treating that replay as complete. Check retention and replay limits with your operator before choosing a new start. start_from=None still uses a saved cursor if available. Starting live can skip historical work. See State and resume.

Check trigger_kind, error_kind and the exception message. For a failed command, exit_code and stderr_tail help identify the cause. A timeout has error_kind="timeout" and timeout_seconds; inspect fields appropriate to that kind rather than assuming every command error has an exit code.

Fix the command, path or receiving service. Retries can help a transient failure, but fail-fast may stop immediately. Set required=False only if continuing without that action is acceptable; it can leave work undone. See trigger settings.

Use with client.listen(...) so context exit calls close(). This cancels and waits for the background listener. The sync iterator checks Python signals while waiting for notifications, but that is not a 100 ms shutdown guarantee. Your loop’s work and cleanup can take longer.

For async code, use async with on the iterator; exit awaits aclose(). Catch KeyboardInterrupt outside asyncio.run() and let cancellation propagate inside tasks. See the async listener.

Create the state file’s parent directory before constructing JsonFileStore. Choose local storage where your account can create the lockfile and replace the state file. Check file contents and permissions if an existing store fails; preserve the file while investigating rather than deleting your resume data. See the complete resuming listener.

A changed URL, event type or filter can select a different resume key. A server schema change alone does not change the key. With no saved cursor, the listener starts live. The default exit policy can leave the final notification uncommitted, so repeats are possible. Enabling exit flushing can skip unfinished buffered work on restart; it is not a work acknowledgement. See Flush on exit.

Synchronous methods block the event-loop thread. Use AsyncAvisoClient in async code and await its HTTP methods. listen() returns an async iterator directly; use async for, not await client.listen(...). See Async.