• Missing libraries on Linux (libgtk-4.so.1, libadwaita-1.so.0): install GTK 4 and libadwaita, e.g. sudo apt install libgtk-4-1 libadwaita-1-0.
• Blank or black window: veetee needs OpenGL 3.3. On Linux check glxinfo -B (package mesa-utils); inside virtual machines enable 3D acceleration.
• Windows: nothing appears, or "OpenGL unavailable": update the graphics driver. Remote Desktop sessions and some virtual machines only offer OpenGL 1.1.
• Windows: SmartScreen warning: releases are signed, but a newly signed version may be asked about until it builds a reputation; choose More info → Run anyway (Windows).
• Windows: a missing DLL: keep the bin, lib and share folders of the zip together; veetee.exe cannot be copied out on its own.

A VT420 (the default model) scrolls smoothly at nine lines a second, as the hardware did, and holds the host back meanwhile. Open Set-Up (F3) → Display, choose Jump Scroll, then Save in the Set-Up Directory. On a VT500 model choose Display → Scrolling mode → Jump, then Save settings.

• Keys click and the bell beeps by default, as on a DEC terminal. Turn the keyclick and bells down or off in Keyboard Set-Up (F3) and Save.
• veetee uses the default audio output; check that one is set in the desktop's sound settings. Without one, veetee reports "no sound" when it starts and uses the desktop bell.
• Building from source on Linux needs libasound2-dev.

Glow, afterglow and the curved screen add a post-processing pass. On a slow or software-only OpenGL (some virtual machines), switch them off under Screen in the window menu.

• Linux: join the dialout group (sudo usermod -aG dialout $USER) and log in again.
• veetee opens the port exclusively; close other programs such as picocom, minicom, PuTTY or ModemManager that hold it.
• Windows: use the name Device Manager shows under Ports (COM & LPT), e.g. --serial COM3.
• Garbled text usually means a speed or parity mismatch; see Connections.

The two ends are at different speeds. veetee changes its end when you leave Communications Set-Up (the subtitle and a message say what it set); the host's end changes with SET TERMINAL/SPEED, or at the next login on a port with Autobaud. Set Set-Up's Transmit speed to match the host and press Return. Closing the window does not log out a serial session, so a host left at 19200 is still at 19200 next time. A host's DECSCS is acted on only at VT500 level, and OpenVMS's SET TERMINAL/INQUIRE selects VT200 mode: see Connections.

• "LAT needs CAP_NET_RAW": the helper that opens the socket has not been granted it. Run sudo setcap cap_net_raw+ep /usr/libexec/veetee-lat-helper — the LAT Services window offers the command with the right path, and a button to copy it. Do this again after every upgrade: the capability belongs to the file, and a new package is a new file.
• "there is none at ...": the helper is missing. In a build tree cargo run -p veetee does not build it; cargo build -p vt-lat-helper does, and it wants the capability again after each rebuild.
• "the Flatpak sandbox does not allow": it does not, and nothing will change that. Use the package or the tarball for LAT.
• Nothing appears in the browser: a node announces itself about once a minute, so give it one. If nothing ever arrives, the cause is usually one of three, and all three look identical — silence:
  • the interface is not the one on the node's segment. LAT does not route, so a node on another subnet cannot be reached at all;
  • veetee is in a virtual machine whose host filters the multicast. Announcements go to 09-00-2B-00-00-0F, and a QEMU/KVM guest behind macvtap is not given them by default: the guest asks for the group and the request is not passed on. On the host, ip link set macvtap0 allmulticast on fixes it now, and trustGuestRxFilters='yes' on the <interface> in the domain XML keeps it fixed;
  • the node is not allowing connections. OpenVMS answers nothing if LATCP says so: MCR LATCP SHOW NODE reports it and MCR LATCP SET NODE/CONNECTIONS=BOTH allows it, with LAT$SYSTARTUP.COM the place to keep it across a reboot.
• Never grant the capability to veetee itself. A GTK program raised by file capabilities does not start: the kernel sets AT_SECURE and GLib refuses to go on.

Fixed in 1.3.0. Pasting more than 255 characters into a LAT session stopped it dead: nothing more echoed, and a minute later veetee said the host had stopped answering. veetee filled a LAT slot to 255 bytes, and OpenVMS drops the circuit when it gets one; it never sends more than 254 itself, and neither does veetee now.

Pasting a lot at the DCL prompt can end in -SYSTEM-W-DATAOVERUN, data overrun: OpenVMS's type-ahead buffer overflowing because the paste arrived faster than DCL reads. From 1.5.0 veetee waits when OpenVMS asks it to, but OpenVMS only asks with SET TERMINAL/HOSTSYNC; set that (in LOGIN.COM, for good) and a long paste arrives whole, over Telnet, SSH or LAT.

• A paper size error means the printer was asked for paper it does not have loaded. From 1.5.0 veetee names the size on every job — your locale's, A4 or Letter — and plain paper, so a printer whose own default is photo paper does not refuse it. Jobs already queued from before may still ask for the wrong paper: cancel them with cancel or the printer's queue.
• Nothing comes out, and veetee said "Sent to …": the job reached CUPS; lpstat -o shows whether it is stuck behind an earlier one, and lpstat -p what the printer says.
• The print dialog appears for every job: choose the printer again with Print to Printer…, which is what lets later jobs go straight to it.
• The host's printed text appears on the screen: that was the case before 1.5.0, which ignored printer controller mode.

See Printing.

• Text keeps its carriage returns at the host when the host's Kermit does not take attribute packets, so does not know the file is text: set text mode there first (SET FILE TYPE TEXT in C-Kermit). C-Kermit takes them, and needs nothing set.
• A cancelled transfer leaves a partial file on OpenVMS: C-Kermit keeps an incomplete binary file by default. SET FILE INCOMPLETE DISCARD at its prompt stops that.
• A line like 9 S~/ @-#&3~^>J)0___N"D7@H appears on the screen when the host was told to SEND before Receive File… was chosen. It is the host's Kermit announcing itself; it is harmless, and the transfer goes ahead.
• Transfers are slow: before 1.4.0, or with a Kermit that does not offer long packets, packets are 94 bytes, about 25 KB/s on a LAN. See File Transfer.
• A transfer over LAT stops part way, or crawls: fixed in 1.4.0. A lost frame froze the session, and lost messages from the host drained veetee's allowance until it sent a slot every three seconds. See below.

Fixed in 1.4.0. A LAT session froze for good the moment one frame from veetee to the host was lost: OpenVMS takes a circuit's messages only in order, so it went on acknowledging and discarded everything after the gap, and veetee never sent anything again. Over Wi-Fi that happened within minutes of a login. The other way round, a message from the host that went missing was skipped, so the text it carried never reached the screen. veetee now sends again what the host has not acknowledged after a second, and holds what arrives after a gap until the host sends the missing message again. If a host takes nothing at all for half a minute, the session ends saying the host stopped accepting what veetee sends, rather than freezing.

A trace (VEETEE_LAT_TRACE, below) counts the retransmissions as resent= in its totals, and losses from the host as missed=, which should stay at nought.

Fixed in 1.1.2. Do not use 1.1.0 or 1.1.1 for LAT. Both are worse than 1.0.0 was, and 1.1.1 is worse than 1.1.0: it kills a session within minutes of any login.

The one that mattered most was the last to be found. veetee took a new sequence number for every message it sent, bare acknowledgements included — and a node acknowledges only the messages that carry slots, since neither end acknowledges an acknowledgement. So a number spent on a keepalive is a number that will never be acknowledged, and the distance between what veetee had sent and what the host had acknowledged grew by one every ten seconds, for ever, whatever else was happening. MCR LATCP SHOW NODE reports a queue limit of 24, and past that the host stopped accepting anything at all: typing went unechoed, SET TERM/INQUIRE timed out into unknown terminal type, and the screen froze on a circuit that was otherwise perfectly healthy. That is the freeze most people would have hit, on every version up to and including 1.1.1.

Underneath it were three more, each real and each fixed:

• Credit lost to dropped frames (up to 1.0.0). Credit is how a LAT node is told it may keep sending, and veetee reckoned what the host had spent by counting what arrived — so a frame that never arrived spent the host's credit without veetee knowing. Every loss left the count one too high, and after eight or so the host had none left and went quiet. Worst over wireless.
• Credit granted for traffic that never existed (1.1.0). The fix for the above read gaps in the host's numbering, but a host's own acknowledgements carry a sequence number too, so counting only the messages with slots read every acknowledgement as a loss. One real session: 165 phantom losses and 1361 credits granted against 107 received, sent as an empty slot apiece.
• A deadlock over what gets acknowledged (1.1.1). A host whose last message carried no slots waits to hear that number back before sending anything else. veetee did not send it, so MYI64 repeated seq=86 every ten seconds for eleven minutes while veetee answered ack=85 — full credit both ways, nothing lost, and the terminal frozen.

And the reason any of them looked frozen rather than disconnected: veetee sent LAT's keepalives from the first and did none of its deciding, so when a host gave up and released the LTA device, veetee went on acknowledging into a circuit that was no longer there — screen stopped, keys still clicking, SHOW DEVICE LTA showing nothing but the template device. Since 1.1.1 a minute of silence ends the session and says so.

If you see anything like it on 1.1.2 or later, ask veetee to write down what is on the wire:

VEETEE_LAT_TRACE=$HOME/lat.log veetee --lat MYI64

Every frame in and out goes into the file, with a line of running totals each minute. The numbers to read first are missed (messages the host sent that never arrived), dup (messages it sent twice, which is it repeating itself for want of an acknowledgement), rewind (messages arriving out of order), credit=ours/theirs — theirs sitting at nought is a session about to go quiet — unacked, which should sit at nought or one — it climbing steadily by one every keepalive is the fault that 1.1.2 fixed — and kernel=in/dropped, the kernel's own count of frames taken in for the socket and frames thrown away before veetee could read them. That last one tells a loss veetee inflicted on itself from a loss on the wire, which a gap in the host's numbering cannot: missed climbing while dropped stays flat is the wire.

It is an environment variable rather than an option so that it covers sessions opened from the connection dialog as well as the command line. Set VEETEE_LAT_TRACE_DATA too and each slot's contents are written out as well: useful, and the file then holds the password typed into the session, in clear, exactly as the wire carries it.

• "flatpak-spawn: command not found" or a shell that exits at once: the Flatpak runs shells, commands and ssh on the host through the Flatpak portal; check that flatpak-portal and flatpak-session-helper are running (they start with the desktop session).
• Saved connections or Set-Up are missing: the Flatpak keeps its own settings in ~/.var/app/com.issinoho.Veetee/config/veetee; copy files from ~/.config/veetee if you used another package before.
• Serial port not found: the Flatpak can open devices in /dev, but still needs the dialout group membership described above.

The terminal is exposed through AT-SPI as a terminal. If Orca says nothing, check that accessibility is on in the desktop settings and that GTK_A11Y is not set to none.

• On OpenVMS run SET TERMINAL/INQUIRE and check SHOW TERMINAL (see OpenVMS).
• Over SSH that inquiry does nothing: OpenVMS never asks, and leaves the _FTAn: device a VT102. Set /DEVICE_TYPE by hand in LOGIN.COM (OpenVMS).
• Your desktop may take F-keys or Ctrl+Shift shortcuts for itself; check the desktop keyboard shortcuts, or move the binding in the Keyboard Map window.
• The keypad follows the LK401 layout: Num Lock is PF1, keypad / is PF2 (Keyboard).
• If you changed the keymap and want the original back, use Restore Defaults in the Keyboard Map window.

Record the session with a checkpoint (Ctrl+Shift+M) at the wrong screen and open an issue with the file attached:

veetee --record problem.vtrec --telnet vms1

Mention the model (--model), the host and application, and what the real terminal shows. Typed keys are not in the recording, but the host's output is; check it for anything private first.