Skip to content

bug(macos): Mac App Store USB printing via CUPS/IPP (needs device repro) #1347

Closed

Description

@khaira777

Parent: #830 (chat leftovers). Needs device repro. platform: macOS (Mac App Store). Verified against main @ 8e39053.

Report

USB receipt printers do not work on the Mac App Store build.

What we know

  • The MAS build routes USB printing through loopback IPP to CUPS, not raw USB: main/printers/thermal.ts isMasBuild (~L306, L358) leads to printViaLocalIpp (main/printers/ipp-client.ts). Added in fix: MAS USB printer support, order-number sanitization, cash-drawer settings #640 (5 Sep). No changes since 6 Sep.
  • build/entitlements.mas.plist has print, network.client and network.server, but no USB device entitlement. This is by design, since CUPS owns the device.
  • No test covers ipp-client.ts / printViaLocalIpp, and docs/printers.md does not explain the MAS requirement (the printer must be added in macOS System Settings > Printers as a raw/generic queue).

Steps

  1. On the MAS build, add a USB ESC/POS printer in macOS Printers (Generic / raw). Select it in FloCafe and print a test receipt.
  2. Capture the FloCafe diagnostics output and the CUPS log (/var/log/cups/error_log).
  3. Try with the printer not added to CUPS, and confirm the error message tells the user what to do.

Acceptance

  • Repro result recorded here.
  • Unit tests for ipp-client.ts (request building, error mapping).
  • A clear in-app error when no CUPS queue exists.
  • The MAS USB setup documented (docs.flopos.com printers page).

Activity

  1. khaira777 commented on Oct 26, 2026

    @khaira777
    ContributorAuthor

    Looking into this issue now.

  2. khaira777 commented on Oct 26, 2026

    @khaira777
    ContributorAuthor

    Reproduction and verification results for macOS App Sandbox CUPS/IPP USB printing (addressed in #1383):

    1. App Sandbox transport check (/System/Library/Sandbox/Profiles/application.sb):
      • The macOS App Sandbox system profile permits (allow network-outbound (literal "/private/var/run/cupsd")) by default, whereas TCP loopback 127.0.0.1:631 requires com.apple.security.network.client and fails with EPERM if restricted.
    2. cupsd idle exit and launchd socket activation (/System/Library/LaunchDaemons/org.cups.cupsd.plist):
      • On macOS, cupsd exits after ~60 seconds of inactivity (IdleExitTimeout 60). launchd only holds /private/var/run/cupsd open for on-demand socket activation; TCP localhost:631 returns ECONNREFUSED while cupsd is idle until woken via the UNIX domain socket.
    3. USB dispatch & IPP raw job submission:
      • printViaUSB now routes through printViaLocalIpp when isMacAppStoreBuild() is true.
      • ippPrintRaw submits raw ESC/POS bytes over /private/var/run/cupsd using application/vnd.cups-raw with fallback to application/octet-stream on 0x040a (client-error-document-format-not-supported).
    4. Without a configured CUPS queue / queue error states:
      • Missing queue (0x0406 client-error-not-found) and no raw queue configured classify as printer_not_found with actionable CUPS Raw queue setup guidance; 0x0506 (server-error-not-accepting-jobs) classifies as queue_unavailable; 0x0508 (server-error-job-canceled) is reported distinctly as a canceled job.
  3. added a commit that references this issue on Oct 26, 2026
    b697a87
  4. added a commit that references this issue on Oct 27, 2026
    9b27bea
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is neededplatform:macosmacOS-specifictype:bugA confirmed defect in existing behavior

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions