Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jalmargyyk/ripe-updater/llms.txt

Use this file to discover all available pages before exploring further.

Most problems with RIPE Updater fall into a small number of categories: authentication mismatches, misconfigured environment variables, prefix validation rules that cause silent skips, or template and S3 configuration errors. This page walks through each common issue, explains why it happens, and tells you how to fix it.
Set DEBUG=yes in your environment to enable verbose logging. This causes RIPE Updater to log the full RIPE REST API request and response bodies, generated RIPE objects, and internal state at each processing step — making almost every problem immediately visible in the container or process logs.
Symptom: Every webhook from NetBox receives a 401 response and the log shows token missmatch.Cause: The Authorisation header value sent by NetBox does not match the UPDATE_TOKEN environment variable configured in RIPE Updater.Two things commonly go wrong:
  1. Wrong header name — The header must use the British spelling Authorisation, not the American Authorization. NetBox’s additional headers field is case-sensitive and spelling-sensitive; using Authorization means the header is never matched.
  2. Token value mismatch — The token in NetBox’s additional headers must be exactly Token <UPDATE_TOKEN> (including the Token prefix and a space), matching the value set in RIPE Updater’s environment.
Fix: In NetBox, navigate to Integrations → Webhooks → your ripe-updater webhook → Additional headers and confirm the entry reads:
Authorisation: Token YOURTOKEN
Then confirm UPDATE_TOKEN=YOURTOKEN in RIPE Updater’s environment (.env file or container environment). Restart RIPE Updater after changing environment variables.
Symptom: The /update endpoint returns 500 and the logs show a BadRequest exception with a 400 response from the RIPE REST API.Cause: The RIPE database rejected the INETNUM or INET6NUM object. Common reasons include:
  • Overlap — A conflicting prefix already exists in the RIPE DB and is not resolvable (it is also present as a prefix or aggregate in NetBox).
  • Template errors — An attribute value in your base template or templates.json is invalid, empty when required, or references a mnt-by, org, or admin-c handle that does not exist in the RIPE database.
  • Invalid attributes — Wrong syntax for a field value (for example, a malformed admin-c NIC handle).
Fix:
  1. Set DEBUG=yes and replay the webhook. The logs will include the full RIPE REST API response body with detailed error messages.
  2. Check the errormessages block in the RIPE API response — it lists each attribute that was rejected and the reason.
  3. If the error mentions overlap, see the “Overlap found but not resolved” entry below.
  4. If you are testing against RIPE_DB=TEST, remember that your real maintainer, org, and person objects do not exist in the TEST database — use the RIPE_TEST_MNT, RIPE_TEST_ORG, and RIPE_TEST_PERSON variables to patch them.
Symptom: A POST /update request returns 200 with the body NotRoutedNetwork, skipping request or ErrorSmallPrefix, skipping request, but you expect the prefix to be processed.Cause: RIPE Updater validates every prefix before touching the RIPE database. It raises one of two exceptions that cause a silent skip:
  • NotRoutedNetwork — The prefix belongs to an address space that should never appear in the RIPE database: RFC1918 private ranges, loopback (127.0.0.0/8, ::1/128), link-local (169.254.0.0/16, fe80::/10), multicast, or any prefix that Python’s ipaddress module considers non-global. These are intentionally skipped with a 200 to avoid NetBox webhook retries.
  • ErrorSmallPrefix — The prefix length exceeds the configured limit. The defaults are SMALLEST_PREFIX_V4=31 (skips /32) and SMALLEST_PREFIX_V6=127 (skips /128). A prefix /27 is fine; a prefix /32 is skipped.
Fix: Confirm the prefix you are testing is a publicly routable address and that its prefix length does not exceed SMALLEST_PREFIX_V4 or SMALLEST_PREFIX_V6. If you need to manage host routes (/32 or /128), lower the SMALLEST_PREFIX_V4 or SMALLEST_PREFIX_V6 environment variable accordingly.
Symptom: The RIPE object is created with the wrong country code, or RIPE Updater logs Default country must be in iso alpha2 format and falls back to DEFAULT_COUNTRY.Cause: Country lookup follows this chain:
  1. RIPE Updater reads data.site.slug from the webhook payload.
  2. It fetches the site from NetBox and walks up the region hierarchy.
  3. For each region, it converts the slug to uppercase and checks whether it matches a key in iso3166.countries_by_name.
  4. If no matching region is found, it falls back to DEFAULT_COUNTRY.
Common causes of failure:
  • The site has no parent region set in NetBox.
  • The region slug does not match any country name in the iso3166 library (for example, nl matches NETHERLANDS — the region slug must be the country’s full name, uppercased, not the alpha-2 code).
  • DEFAULT_COUNTRY is not set or is not a valid ISO 3166 alpha-2 code (for example, DE or NL).
  • data.site is null in the webhook payload (prefix has no site assigned in NetBox).
Fix: In NetBox, ensure each site has a parent region whose slug matches a country name from the iso3166 library when uppercased. For example, a slug of netherlands resolves to country code NL. Set DEFAULT_COUNTRY to a valid alpha-2 fallback such as DE.
Symptom: The RIPE object is submitted with an empty or None org attribute, or RIPE Updater logs that org returned None.Cause: Organisation lookup reads the lir custom field from the parent aggregate of the prefix in NetBox, lowercases it, and searches for a matching key in lir_org.json. If the key is not found, org() returns None.Common causes:
  • The aggregate in NetBox does not have the lir custom field set.
  • The lir value in NetBox does not match any key in lir_org.json. The comparison is case-insensitive (both sides are lowercased), but spelling must match exactly.
  • lir_org.json does not exist at TEMPLATES_DIR/lir_org.json or is malformed.
Fix: Open lir_org.json and confirm the key for your LIR is present and spelt correctly. Then check the lir custom field on the parent aggregate in NetBox. For example, if the custom field is set to De.ExampleLIR1, the lir_org.json key must be "de.examplelir1".
Symptom: After a successful RIPE DB operation, RIPE Updater raises a RuntimeError with a message like unable to connect to SMTP server: 127.0.0.1 - [Errno 111] Connection refused and the request fails.Cause: MAIL_REPORT=yes is set but RIPE Updater cannot reach the SMTP server specified in the SMTP environment variable. The notify() function in functions.py attempts an SMTP connection after every RIPE DB operation (create, update, or delete). If the connection fails, it raises RuntimeError with the error detail.Note that this error occurs after the RIPE DB operation has already succeeded, so your RIPE object may have been updated even though the HTTP response indicates failure.Fix:
  1. Confirm the SMTP variable is set to the correct hostname or IP address of your mail relay.
  2. Test connectivity: nc -zv <SMTP_HOST> 25 from the RIPE Updater host or container.
  3. If you do not need email reports, set MAIL_REPORT=no to disable the SMTP call entirely.
  4. If you need STARTTLS, set SMTP_STARTTLS=yes.
Symptom: RIPE Updater raises RuntimeError: No template file /opt/ripeupdater/templates/templates.json (or a similar path) and the request fails with 500.Cause: The read_json_file() function checks whether the template file exists at the path constructed from TEMPLATES_DIR. If the file is not found, it raises RuntimeError immediately.Common causes:
  • The Docker volume mount is missing or points to the wrong host path. The container expects templates at TEMPLATES_DIR (default /opt/ripeupdater/templates).
  • templates.json, lir_org.json, or a base template file is missing from the mounted directory.
  • TEMPLATES_DIR is overridden to a path that does not exist inside the container.
Fix: Confirm the volume mount in your docker run command or docker-compose.yml:
-v "/path/to/your/templates:/opt/ripeupdater/templates:ro"
Then verify the directory contains templates.json, lir_org.json, and all base template files referenced by inherit keys in templates.json.
Symptom: RIPE Updater raises a ClientError or botocore exception during startup or when processing a webhook, referencing S3 connectivity or authentication.Cause: When S3_BACKUP=yes, BackupManager.__init__() immediately connects to S3 and attempts to create the configured bucket. If any credential or endpoint variable is wrong, the error surfaces at startup rather than during backup operations.Fix: Check each of the following environment variables:
VariableDescription
S3_ENDPOINT_URLFull URL of your S3-compatible endpoint, e.g. https://s3.example.com
S3_ACCESS_KEYAccess key ID for your S3 storage
S3_SECRET_ACCESS_KEYSecret access key for your S3 storage
S3_BUCKETName of the bucket to use (created automatically if it does not exist)
Test connectivity from the container before enabling S3_BACKUP=yes:
curl -v https://your-s3-endpoint/
Symptom: A POST /update returns 500 and the logs show Overlap found for <prefix>: <overlapping-prefix> after a RIPE DB 400 response.Cause: When creating a new INETNUM or INET6NUM object, RIPE Updater checks for overlapping entries. If an overlapping prefix is found, it queries NetBox to determine whether the overlapping prefix exists as a prefix or aggregate in NetBox. If the overlapping object exists in NetBox, RIPE Updater refuses to delete it automatically and reports the overlap as an error.This situation arises when:
  • A parent prefix and one of its children both have ripe_report=true (see Known limitations).
  • A stale RIPE object from a previous allocation overlaps with your new prefix and was not cleaned up.
  • The overlapping object exists in the RIPE database and also appears as a prefix or aggregate in NetBox.
Fix: You must resolve the overlap manually:
  1. Identify the overlapping prefix from the error message.
  2. If the overlap is intentional (parent + child both flagged), disable ripe_report on one of them.
  3. If the overlapping RIPE object is stale, delete it directly via the RIPE database interface or REST API, then retry the webhook.

Build docs developers (and LLMs) love

Get started for freeTalk to us