Troubleshooting

Find what you see in the tables below. Each section links to the guide with more detail.

Get help

If this page doesn’t solve it, use Send feedback, at the bottom of the Traps panel and in other panels. It starts a note for the part of Akema you’re in, and can add diagnostics: your Akema version, operating system and license type. Email it to feedback@akema.io, or copy or download it. Your messages aren’t included.

To help us reproduce a problem, include:

What you did and what you expected
The exact error text, copied from the screen
For connection problems, the kind of cluster (self-managed, MSK, Confluent Cloud, Event Hubs) and the security settings you chose, never passwords

Install and start

What you see	Why	What to do
`failed to listen on 127.0.0.1:8080: … address already in use`	Another program, or another copy of Akema, is using the port	Stop the other program, or start Akema on another port: `akema -addr 127.0.0.1:8081`
The browser can’t reach Akema in Docker	The port isn’t published, or is published to a different address	Run with `-p 127.0.0.1:8080:8080` and open `http://127.0.0.1:8080`
`GLIBC_2.xx not found`	Linux is older than glibc 2.28	Use the Docker image
macOS says the app is damaged, or Windows SmartScreen blocks it	The beta builds aren’t signed yet	See macOS or Windows in the install guide
The sign-in page appears again	You signed out, Akema restarted, or you hadn’t used it for 12 hours. `localhost` and `127.0.0.1` also need separate sign-ins	Sign in again, and use the same address each time. See Sign-in and sharing
`Invalid passphrase` or `Invalid credentials` when signing in	The passphrase, name or PIN is wrong. Names are lowercase	Check with whoever runs Akema. If the passphrase is lost, they can turn sign-in off and set it again
Viewing — another window is editing, and changes don’t work	Another browser is the editor	Choose Take over. See One editor at a time
View-only, with no Take over	You’re signed in as a viewer	Ask whoever runs Akema to make you an editor
Teammates using a host name see the page, but nothing updates and changes fail	Akema only accepts changes from addresses it knows	Start Akema with `-auth-host` and that name. See Share on your network
A script’s changes are refused	A browser holds the editor role, or sign-in is on and the script hasn’t signed in	See Scripts
Workspaces or settings are missing after an upgrade or move	Akema is using a different data folder	Check the data folder, or pass `-data-dir`

Connect to Kafka

What you see	Why	What to do
`broker unreachable (… connection refused)` or a timeout	Akema’s machine can’t reach the bootstrap address	Check the host, port, firewall, VPN or security group
`… Local: Broker transport failure`	The security settings don’t match the port	Set TLS and SASL to match the cluster’s listener
An error about authentication or SASL	Wrong credentials or mechanism	MSK uses `SCRAM-SHA-512`; Confluent Cloud and Event Hubs use `PLAIN`
`Topic authorization failed`	No permission to read the topic	Grant Describe and Read on the topic
Test OK, but nothing arrives	Brokers’ advertised addresses aren’t reachable, or there’s nothing to read from the start position	See Network access and try Start mode Earliest
`License expired — open Settings → License.`	The trial ended, or the license is for another machine	See License below

Messages don’t appear in Inspect

What you see	Why	What to do
Received stays at 0	Start mode is Latest (tail) and nothing new has been produced, or the start offset or time is past the last message	Change Start mode to Earliest or Last N
The source shows as stopped	It was stopped from its pill, or stopped by Max read or Stop offset	Start it again from its column on Connect. Clear Max read and Stop offset for a continuous stream
Far fewer rows than Received	The table keeps the newest 800 messages per browser tab by default, and Sample every keeps 1 in N	Raise the browser buffer under Settings, and set Sample every to 1
Only trapped rows are shown	Traps only is on, or the table is filtered to one trap	Turn off Traps only, or choose Clear filter in the Traps panel
Rows stop updating and then catch up	The browser lost its connection to Akema	Akema reconnects on its own, within 10 seconds, and reloads recent rows

Avro and Protobuf decoding

A message that can’t be decoded shows an ERR chip, and the Record pane shows the error with a hint. The rest of the stream continues.

What you see	Why	What to do
An error mentioning the registry, or an HTTP status	Akema can’t reach Schema Registry, or the credentials are wrong	Check Registry URL, Registry user and Registry pass. Confluent Cloud needs a Schema Registry API key, not the cluster key
An error mentioning the wire format or magic byte	Wire doesn’t match how the producer framed the message	Try Auto, then Confluent or Raw
An Avro decode or parse error	The schema doesn’t match the message	Check the subject and version, or upload the schema the producer used
Protobuf messages decode as `{}`	Akema picked the wrong message type from the `.proto` file	Put the message type the producer sends first in the file and upload it again
Values show as text that looks like bytes	Format is JSON / text or Bytes	Set Format to Avro, Protobuf or Auto with a registry or uploaded schema

Traps

What you see	Why	What to do
A new trap has no hits	Traps only check messages that arrive after they’re saved	Re-read the source with ↻ on its pill
A trap never matches	A field path is wrong, or a number is stored as text	Create the trap from the field in the Record pane, or use `double(value_json.field)`
`undeclared reference to …` when saving	The function is a CEL extension that Akema doesn’t include	See what’s available

Files (fixtures)

What you see	Why	What to do
`csv exceeds max size`, `json exceeds max size` or `file exceeds max size`	Files can be up to 64 MB	Split the file, or keep only the columns and rows you need
`csv exceeds max rows`	Files can have up to 250,000 rows	Split the file. For Parquet, use Row mode Last N or Sample every
`csv has … columns (max 64)`	Files can have up to 64 columns	Drop columns you don’t need
`csv must be valid UTF-8`	The file uses another text encoding	Save it as UTF-8
`csv has no payload columns`	Every column was mapped to the key or time	Leave at least one column for the message value
`csv has header but no data rows`	The file only has a header row	Check that the file has data
Parquet files won’t load after the trial	Parquet needs a trial or license; CSV and JSON don’t	Add a license
`nested parquet projection … is not supported`	Only top-level Parquet columns can be selected	Choose top-level columns
`fixture file is not saved — Load the file again`	The file wasn’t kept with the workspace	Choose the file and Load again
Message times are wrong or all the same	No `timestamp` or `ts` column, so Akema used load time	Name the time column `timestamp`, or map it with Mapping…

Explore

What you see	Why	What to do
Explore shows old data	Load takes a snapshot; it doesn’t follow the stream	Choose Load again, or turn on Live in the Explore toolbar
Explore has fewer messages than Inspect received	Explore keeps the newest 10,000 messages per source by default	Raise Explore rings under Settings
`Explore snapshot was cleared. Reload to query the redacted window.`	A redaction profile was turned on or changed	Choose Load again
A note that a Load mixes in a fixture	Redaction doesn’t apply to fixtures	Expected: the fixture’s rows aren’t redacted, even where a Kafka topic with the same name is

PII redaction

What you see	Why	What to do
No Kafka source will start in a workspace	The saved redaction profile is invalid, so Akema refuses to show unredacted data	Fix or remove the profile; files still load meanwhile
body dropped on messages	The value isn’t JSON, and Unstructured is Drop body	Expected. Choose Pass through only if those messages can’t contain personal data
redacted, field error on messages	A value didn’t suit its technique, so Akema replaced it with `null`	Choose a technique that fits the field’s type
Original values came back after turning a profile off	They didn’t: turning a profile off shows new messages unredacted	Expected. Messages read while the profile was on stay redacted
`invalid path … segment …`	That path part is empty, or the name needs brackets	See Paths

Memory and speed

Every buffer in Akema has a size limit, shown and set on the Settings tab. Nothing changes until you choose Apply. See Settings for what each one does.

What you see	Why	What to do
Akema uses more memory than you’d like	Several sources each keep their own buffers	Lower Explore rings and the consumer buffer under Settings, or Max buffer per source
The browser tab is slow on a busy topic	The table is redrawing thousands of messages a second	Turn on Traps only, set Sample every, or choose the high_volume profile under Settings, which keeps 1 in 150 messages
A teammate’s view changed when you applied a setting	Most settings apply to everyone using this Akema	Settings marked for this browser only, such as the browser buffer, affect just you
No Apply button	Another window is editing, or you’re signed in as a viewer	See One editor at a time

License

What you see	Why	What to do
`License expired — open Settings → License.`	The 14-day trial ended	Add a license. CSV and JSON files keep working
`file not bound to this instance — send fingerprint to fulfillment`	The license was issued for another machine or Docker volume	Run `akema -license-fingerprint` on this machine and send the result with your order
Docker starts a new trial each time	No volume for `/data`	Add `-v akema-data:/data -e AKEMA_DATA_DIR=/data`