Troubleshooting & FAQ

Files

A file will not open

Refract validates content as well as the extension. Check that:

• The extension is supported: .csv, .tsv, .txt, .parquet, .pq, .arrow, .wav, .caf.
• A text file is UTF-8 with consistent row lengths and at least one numeric field.
• A Parquet file has at least one numeric column.

A column is missing

Parquet exposes numeric columns only. For CSV, check whether the first row was treated as a header.

The line has gaps

Values that do not parse as numbers become NaN, which breaks the line. This usually means a malformed row or a sentinel such as N/A.

Live connections

Connected, but no traces

Open View Raw Stream and work down the layers:

1. No bytes at all — a transport problem. Check the port, device and baud rate.
2. Out-of-frame entries — a framing problem. Check the delimiter, length header, frame size or sync pattern.
3. Correct frames but no columns — a decoder problem. CSV needs a header record if First line is a header is on; binary needs a packet layout; protobuf needs a message type.

The numbers are wrong

Usually byte order or field width. Switch the field between LE and BE, and check the total bytes per sample against your device's packet size. Model unused bytes as padding rather than omitting them.

Devices do not appear

Serial, HID and Bluetooth each need a macOS permission. Re-enable Refract in System Settings → Privacy & Security, and use the refresh button after connecting a device.

A TCP client cannot connect

Refract is the server. Start the connection first — the browser should read Listening — then start your producer.

Old samples disappear

Live sources keep a rolling window. Increase it in the connection's buffer settings, or enable Persist to database.

The view stopped following new data

Adjusting the x zoom or panning switches Follow live off. Press ⌘L to re-enable it.

Formulas

"More than one signal is called…"

Qualify the name — [run1.csv].voltage — or click the signal in the Library, which inserts the qualified form.

"& needs an int"

The signal is a float. Wrap it in int() to round it, or bits() to reinterpret a float's bit pattern. Signals from a source that declares an integer type take bitwise operators directly; a CSV column never does, since delimited text declares no type. See Types.

The result is blank at the start

Positions before an input's first sample are NaN. The preview's NaN count shows how many samples are affected.

"non-monotonic x-axis" warning

An input is plotted against a non-increasing custom x-axis and must be sorted before evaluation. The curve still draws as recorded. See Alignment.

A computed signal went grey

It is broken: an input is no longer available. Reopen the source and re-save the formula.

Display

Everything looks flat

One signal with a much larger range is dominating autoscale. Move it to its own track or hide it.

The y-axis will not rescale

Zooming or panning y switches the track to manual. Double-click the y-axis, or press ⌘R.

A WAV plots in the tens of thousands

Integer PCM is plotted in the counts it was sampled in, not normalised to ±1.0, so a 16-bit file spans −32768…32767. Autoscale handles it. Divide by the full-scale value in an in-place edit if you want the normalised form. See Audio.

Two files do not line up

They are on different x-axes. Assign a timestamp column as the x-axis for each and set matching transforms. See The x-axis model.

Data handling

Refract processes files and streams locally. Nothing you open is sent to us.

Refract writes only to your Application Support folder, under Refract:

Packet layouts and exported presets are saved wherever you choose. See the Privacy Policy.

FAQ

What formats can Refract open?

CSV, TSV and TXT; Parquet; Arrow IPC; WAV and CAF audio. See Supported formats.

Can I use Refract with my own pipeline?

Yes. Anything that writes to a TCP socket, serial port, HID report or BLE characteristic can feed Refract. See Sending data to Refract.

Why is my first column not the x-axis?

Every column becomes a trace; assign the x-axis explicitly. See Assigning a custom x-axis.

Can I make a scatter plot?

Assign one signal as another's x-axis and set the draw mode to Marker.

Can I export a plot?

There is no image or data export. Streams can be captured to Arrow with Persist to database.

Support

Use the contact form and include:

• Your Mac model and macOS version, and the Refract version from Refract → About Refract.
• What you did, and what happened instead.
• For file issues: the format, and a sample if you can share one.
• For streaming issues: the transport, decoder and framing, and what the raw stream console shows.