Troubleshoot real-time

Real-time data moves through a fixed sequence of stages: an event arrives on an event stream, updates a profile in a profile collection, changes the profile’s real-time segment memberships, and moves the customer through a real-time journey. When something doesn’t work, find the first stage where the data stops, and start there. For how each stage works, see Real-time.

Where to look

Each stage has a place to inspect what Amperity received and did.

Stage	Where	What it shows
Event stream	The stream’s Explorer tab	A random sample of recent events for each event type, filtered as valid, invalid, or ignored.
Profile collection	The collection’s Profile viewer tab	A customer’s profile, with tabs for Recent events, Keychain, Profile, Segments, and Activations. Recent events shows only recent activity, for diagnosis, and may not show an event the moment it’s processed.
Real-time API	The collection’s APIs tab	Calls to the Real-time API’s event, profile, and segment endpoints from the browser, with a cURL example of each request.
Real-time segment	The segment’s Overview and Customers tabs	The segment’s member count and how it has changed, and the profiles in it.
Real-time journey	Destinations set to Test, View test results, and the travel log	What the journey would do without sending to live destinations, and each step every traveler took and why they exited.

The Explorer tab’s samples, an event type’s Samples tab, and the Profile viewer, APIs, and Customers tabs require permission to view personal data. Without it, the Explorer tab appears but shows no events.

The sender receives an error

A system that sends events with POST /prof/events/{stream-id} receives one of these responses. See the Real-time API reference for every response.

Response	Cause and fix
202 Accepted	The event was accepted for processing. Processing is asynchronous, so a 202 doesn’t mean the event matched a profile. If the event doesn’t appear in the profile, see Events don’t update a profile.
204 No Content	The stream’s Event stream mode is Drop. The event was accepted but isn’t processed. Set the mode to Process.
400 Bad Request	The request body isn’t a single JSON object.
404 Not Found	No event stream has that ID. Copy the stream ID from the stream’s endpoint configuration.
409 Conflict	The stream’s Event stream mode is Reject. Set the mode to Process.
411 Length Required	The request has no Content-Length header.
413 Payload Too Large	The event is larger than 64 KiB. Send fewer fields, or split the event.
503 Service Unavailable	Amperity couldn’t accept the event. Retry the request. Contact your Amperity representative if 503 responses continue.

Events are unrecognized, ignored, or invalid

A stream’s Explorer tab samples events by event type, and shows each as valid, invalid, or ignored. Events that don’t resolve to an event type appear under Unrecognized events, and the stream’s overview counts them as Unrecognized.

Symptom	Cause and fix
The event is unrecognized	The stream’s Recognition method didn’t resolve the event to an event type name. Check that the property it reads is present in the event, or that the expression returns a value for it.
The event is ignored	The event resolved to a name, but the stream has no event type configured for that name. Add an event type for it, or correct the name the recognition method produces.
The event is invalid	The event matched an event type, but a required property has no value, a property’s expression failed to evaluate, or the event’s timestamp is missing or isn’t a timestamp. Compare the event with the event type’s Properties, and correct the event or the event type.

Events don’t update a profile

Symptom	Cause and fix
Valid events don’t reach any profile in the collection	The collection doesn’t receive events from that stream. Add the stream under Event stream selection in the collection’s event assignment.
Some valid events don’t reach a profile	The event has no value for any property assigned a Keychain key on the event type, or its keychain keys aren’t in the collection’s keychain, so Amperity can’t match it to a customer. Assign a Keychain key to the event’s identifier properties, check that the collection’s keychain includes those keys, and check that the sender includes the values.
Events for a new customer don’t create a profile	Just-in-time profile creation is off for the tenant, so an event whose identifiers match no profile isn’t applied. Contact your Amperity representative.
A new customer’s first event takes a moment to appear	Amperity holds an event for a new customer until the new profile’s keychain entries are in place, and then applies it. An event that is still held after two hours is dropped. See Just-in-time profile creation.
An event updates a different profile than expected	The event’s identifiers belong to more than one profile. Amperity merges a profile created in real time into one that Stitch knows, but it doesn’t merge two customers Stitch resolved separately: the event updates the profile whose identifier comes first in the collection’s keychain priority order. See When an event matches more than one profile.

A lookup returns 404

A Real-time API lookup returns 404 when no profile in the collection matches. A lookup with no identifiers returns 400.

Symptom	Cause and fix
One identifier finds the customer, but another doesn’t	The second identifier isn’t in the keychain. Stitch can associate one value with more than one customer, and a value like that is left out of the keychain rather than resolved ambiguously. Open the customer in the Profile viewer and check the Keychain tab for the identifier.
A lookup by Amperity ID returns nothing for a customer in your database	The customer has no value for any of the collection’s keychain keys. After a keychain refresh, Amperity removes profiles that have no keychain values, so the customer isn’t in the collection.
A customer who is new in Stitch isn’t found	The keychain refreshes from Stitch’s output after each run of the collection’s database, and only when the collection refreshes automatically. See Profiles don’t refresh.
A lookup with several identifiers returns a different customer than expected	A lookup tries the identifiers in the collection’s keychain priority order and returns the first profile that matches. Send the most specific identifier, or only the one you want to match on.

Profiles don’t refresh

Symptom	Cause and fix
Database attributes and the keychain never update	Automatically refresh profiles after each database run? isn’t selected on the collection. Select it, or use Refresh profiles to refresh the collection once.
Profiles didn’t refresh after Stitch ran	The refresh follows a run of the collection’s database, not the Stitch run itself. Check that the collection’s database ran and published after Stitch.
Profiles didn’t refresh after the daily workflow	Check that the daily workflow ran the collection’s database. The refresh runs only after that database publishes.

An attribute doesn’t change when expected

Symptom	Cause and fix
A time-based computed attribute never becomes true	Only timestamp_in_last, timestamp_in_next, date_in_last, and date_in_next are recalculated as time passes. An attribute built on another function, such as timestamp_diff, changes only when the profile changes. Rewrite the condition with one of the four functions. See Expressions.
An event attribute counts more or fewer events than expected	The attribute’s Event scope covers a different set of events: one event type, one stream, or all events. Or its Where condition filters them. Check both.
An event attribute changes at an unexpected time	Lookback window durations are whole hours, days, or weeks, aligned to UTC, with weeks starting on Monday. A window isn’t measured to the second from the current time.

A segment looks wrong

Symptom	Cause and fix
A new or edited segment has no members yet	Its Status is Queued or Updating while Amperity evaluates the collection’s existing profiles. Wait for Ready.
The member count is a dash	A dash means membership hasn’t been computed yet. A 0 means it has been computed and the segment has no members.
A profile meets the conditions but isn’t in the segment	Check the profile’s attribute values on the Profile tab of the Profile viewer, and its memberships on the Segments tab. A condition on an attribute that hasn’t updated yet, such as a database attribute waiting for the next refresh, holds the customer out.
The segment can’t be edited in Visual mode	The expression can’t be shown in the visual editor, such as one that combines conditions with OR. Edit it in Code mode.

A journey has no travelers or doesn’t send

Symptom	Cause and fix
No customers enter the journey	The journey’s Status is Paused. Set it to Running and save the journey.
Customers already in the entry segment don’t enter	A customer enters a real-time journey only when they join an entry segment. Customers who were already in the segment when the journey started don’t enter until they leave the segment and join it again.
Some customers who join the segment don’t enter	An Exclude segment is keeping them out, or re-entry is keeping them out: Allow re-entry is off, they are within the Cooldown period, or they are in a Linked journeys journey or within its cooldown.
Travelers enter but nothing reaches the destination	Destinations is set to Test, which sends nothing to live destinations. Set it to Live.
Travelers wait longer than expected before a message	A Delay step is waiting, or a Quiet Hours step is holding travelers until the quiet window ends in their time zone. Quiet hours use the Timezone attribute on each profile, or the Fallback timezone when it has no value.

Messages continue after a traveler converts

Leaving the entry segment doesn’t remove a traveler from a real-time journey. A customer who abandons a cart and then buys it stays in an abandoned cart journey until an exit condition removes them or they reach the end of their path.

Add an exit condition for every reason a traveler should stop: an Event type, such as the order event, a Real-time segment of customers who converted, or another Real-time journey that takes priority. See How travelers leave.

When to contact your Amperity representative

Contact your Amperity representative when:

• the Real-time API returns 503 responses repeatedly,

• events are valid and match a profile, but the profile doesn’t update,

• a new customer’s events never create a profile,

• or a problem continues after every check on this page passes.

Include the tenant, the event stream or collection, an example event ID or profile ID, and the time the problem started.