Source file#
src/data/knownIssues.json
[
{
"id": "boot-elf-black-screen-on-igr",
"title": "Black screen after accepting POPStarter IGR exit",
"symptom": "IGR popup appears, user chooses YES, then the console hangs on black screen.",
"likelyCauses": [
"Incompatible BOOT.ELF target",
"POPStarter's own ELF loader exit path",
"OPL/fork exit behavior mismatch"
],
"mitigation": "Use $IGR5 for no-popup direct close. If BOOT.ELF chaining still black-screens, use loader-disable PATCH_9.BIN in the POPS folder or replace/recompress BOOT.ELF.",
"sourceIds": [
"psx-place-popstarter-page-15",
"psx-place-popstarter-page-4"
],
"confidence": "high",
"verificationStatus": "verified-primary"
},
{
"id": "hdtvfix-accidental-480i",
"title": "Expected 240p but POPStarter outputs interlaced video",
"symptom": "Game appears in 480i/576i instead of PS1-style 240p/288p.",
"likelyCauses": [
"$HDTVFIX present in CHEATS.TXT",
"Modified POPSTARTER.ELF"
],
"mitigation": "Check the per-game CHEATS.TXT first; remove $HDTVFIX unless the target display requires it.",
"sourceIds": [
"psx-place-popstarter-page-15"
],
"confidence": "high",
"verificationStatus": "verified-primary"
},
{
"id": "hdd-opl-network-auto-hang",
"title": "HDD POPStarter launched from OPL Apps hangs with HDD LED stuck",
"symptom": "Black screen and fixed HDD activity light when launching HDD POPStarter ELF from OPL Apps.",
"likelyCauses": [
"OPL network/BDM/SMB start modes set to Auto",
"OPL waits indefinitely on network path before HDD launch"
],
"mitigation": "Set non-needed OPL devices to Manual or Disabled before launching HDD POPStarter through Apps.",
"sourceIds": [
"elotrolado-pops-thread",
"psx-place-popstarter-page-15"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "smb-config-typos",
"title": "SMB config ignored because filenames are wrong",
"symptom": "SMB launch cannot connect or appears to ignore network configuration.",
"likelyCauses": [
"Files named IPCONFIG.DAY or SMBCONFIG.DAY",
"poweroff.irc typo",
"Wrong capitalization"
],
"mitigation": "Use IPCONFIG.DAT, SMBCONFIG.DAT, and poweroff.irx as shown in the ElOtroLado first post.",
"sourceIds": [
"elotrolado-pops-thread",
"user-notes"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "hdd-partition-name",
"title": "HDD returns to Browser or freezes because __.POPS is misspelled",
"symptom": "Game launch returns to the PS2 Browser, freezes at logo, or cannot find VCDs.",
"likelyCauses": [
"Missing dot in __.POPS",
"Wrong case",
"VCD not in the POPStarter partition"
],
"mitigation": "Use hdd:/__.POPS/ exactly for VCDs and hdd:/__common/POPS/ for common POPS files.",
"sourceIds": [
"elotrolado-pops-thread",
"psx-place-popstarter-page-4"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "usb-fragmentation-and-clusters",
"title": "USB videos stutter or games slow down",
"symptom": "FMVs stutter, loading is poor, or audio/video is unstable on USB.",
"likelyCauses": [
"USB 1.1 bandwidth",
"FAT32 fragmentation",
"Small cluster size",
"Problematic flash drives"
],
"mitigation": "Use a USB HDD where possible, FAT32 64K clusters if compatible, and avoid repeated copy/delete churn.",
"sourceIds": [
"elotrolado-pops-thread"
],
"confidence": "medium",
"verificationStatus": "verified-single-source"
},
{
"id": "smbv1-security",
"title": "SMB requires legacy configuration",
"symptom": "Modern Windows/NAS share cannot be reached by POPStarter.",
"likelyCauses": [
"SMB1/CIFS disabled",
"Anonymous/guest access blocked",
"Port 445 blocked",
"Share not writable for VMC"
],
"mitigation": "Use an isolated network/share if enabling legacy SMB behavior; prefer a dedicated PS2 share with write permission for VMCs.",
"sourceIds": [
"psx-place-popstarter-thread",
"elotrolado-pops-thread"
],
"confidence": "medium",
"verificationStatus": "verified-cross-source"
},
{
"id": "opl-apps-title-cfg-txt",
"title": "OPL Apps entry missing because title.cfg was saved as .txt",
"symptom": "The app entry does not appear, or the entry launches nothing.",
"likelyCauses": [
"File is named title.cfg.txt",
"title.cfg is in the wrong APPS folder",
"boot= does not match the renamed ELF filename"
],
"mitigation": "Save the file as plain text named exactly title.cfg, put it beside the renamed ELF, and make boot= match only that ELF filename.",
"sourceIds": [
"user-notes"
],
"confidence": "high",
"verificationStatus": "verified-hardware-user"
},
{
"id": "per-game-folder-basename-mismatch",
"title": "CHEATS, VMC, or fixes ignored because the per-game folder name is wrong",
"symptom": "The game boots, but CHEATS.TXT, VMC sharing, or Hugopocked fixes do not apply.",
"likelyCauses": [
"Support folder includes .VCD extension",
"Support folder uses display title instead of VCD basename",
"HDD fixes placed under __.POPS instead of __common/POPS"
],
"mitigation": "Name the support folder after the VCD basename without .VCD: mass:/POPS/<Game>/ on USB, hdd:/__common/POPS/<Game>/ on HDD, and smb:/POPS/<Game>/ on SMB.",
"sourceIds": [
"user-notes",
"elotrolado-pops-thread"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "cheats-txt-case-sensitive-path",
"title": "CHEATS.TXT ignored because the filename case is wrong",
"symptom": "Named commands or raw cheat codes do nothing, especially on internal HDD/PFS.",
"likelyCauses": [
"File saved as CHEATS.txt or cheats.txt",
"Case-sensitive PFS path",
"File placed in the wrong per-game support folder"
],
"mitigation": "Rename the file to uppercase CHEATS.TXT and place it in the folder matching the VCD basename.",
"sourceIds": [
"popsloader-docs-reference",
"elotrolado-pops-thread"
],
"confidence": "high",
"verificationStatus": "recovered-cross-check"
},
{
"id": "usb-pops-split-support-files-missing",
"title": "USB POPS0-POPS9 game boots without expected patches or handlers",
"symptom": "A game in POPS0 through POPS9 launches, but BIOS.BIN, PATCH_#.BIN, TROJAN_#.BIN, or VMCDIR.TXT behavior is missing.",
"likelyCauses": [
"Support files left only in mass:/POPS",
"Assuming POPS_IOX.PAK propagation rules apply to every handler file",
"Per-folder patch/handler files not copied into the split POPS# folder"
],
"mitigation": "Keep POPS_IOX.PAK and IGR TM2 textures in mass:/POPS, but copy BIOS.BIN, PATCH_#.BIN, TROJAN_#.BIN, and VMCDIR.TXT into every POPS# folder that needs them.",
"sourceIds": [
"popsloader-docs-reference",
"shaolin-bitbucket-wiki"
],
"confidence": "high",
"verificationStatus": "recovered-cross-check"
},
{
"id": "hdd-leading-plus-pops-partition",
"title": "HDD VCD folder created as +__.POPS instead of __.POPS",
"symptom": "Modern HDD launch cannot find VCDs even though a similarly named partition exists.",
"likelyCauses": [
"Using OPL app partition naming rules for POPStarter's VCD partition",
"Adding a leading plus to __.POPS",
"Confusing +OPL/APPS with POPStarter's VCD partition"
],
"mitigation": "Use hdd0:/__.POPS/ for VCDs and hdd0:/__common/POPS/ for shared POPS files and per-game support folders.",
"sourceIds": [
"popsloader-docs-reference",
"elotrolado-pops-thread"
],
"confidence": "high",
"verificationStatus": "recovered-cross-check"
},
{
"id": "old-rip-build-selected",
"title": "Old RIP or WIP build used instead of the final 2019 r13 beta",
"symptom": "Documented final-build behavior such as $IGR5 or later config-byte meanings does not match the user's setup.",
"likelyCauses": [
"Using POPStarter_r13_RIP_06",
"Using an older WIP/OBT package",
"Mixing old wiki instructions with the final 2019 build"
],
"mitigation": "Treat POPStarter r13 Beta 2019-06-05 as the canonical final public build unless deliberately testing an older build.",
"sourceIds": [
"popsloader-docs-reference",
"retro-jogos-home"
],
"confidence": "high",
"verificationStatus": "recovered-cross-check"
},
{
"id": "smb-debug-build-myth",
"title": "SMB debug text mistaken for a required debug build",
"symptom": "SMB launch shows startup/debug text and the user assumes the wrong POPStarter build was used.",
"likelyCauses": [
"SMB mode forces visible status text",
"Confusing $410 debug byte labels with SMB-mode behavior",
"Old forum claims about debug builds"
],
"mitigation": "Do not chase a separate debug build just because SMB startup text is visible. Focus on SB. prefix, memory-card modules, IPCONFIG.DAT, SMBCONFIG.DAT, and share write permission.",
"sourceIds": [
"popsloader-docs-reference",
"elotrolado-pops-thread"
],
"confidence": "high",
"verificationStatus": "recovered-cross-check"
},
{
"id": "smb-prefix-or-protocol-mismatch",
"title": "SMB launch fails because the prefix or OPL SMB protocol name is wrong",
"symptom": "The SMB app entry starts then black-screens, or OPL Apps does not launch the ELF.",
"likelyCauses": [
"Renamed ELF lacks SB. prefix",
"conf_apps.cfg uses smb: on an OPL beta expecting smb0:",
"Path has trailing spaces",
"APPS path does not match the renamed ELF exactly"
],
"mitigation": "Use SB.<Game>.ELF for SMB POPStarter launchers. For newer OPL betas, try smb0:/APPS/SB.<Game>.ELF if smb:/APPS/SB.<Game>.ELF does not work.",
"sourceIds": [
"elotrolado-pops-thread",
"user-notes"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "smb-vmc-write-failure",
"title": "SMB game boots but VMC saves fail",
"symptom": "The game launches over SMB, but memory card files are not created or saves do not persist.",
"likelyCauses": [
"Share is read-only",
"Guest user lacks write permission",
"NAS blocks anonymous writes",
"Per-game folder cannot be created"
],
"mitigation": "Give the configured SMB user or guest account write permission on the share. POPStarter creates/updates SLOT0.VMC and SLOT1.VMC over SMB.",
"sourceIds": [
"elotrolado-pops-thread"
],
"confidence": "high",
"verificationStatus": "verified-single-source"
},
{
"id": "bdm-exfat-wrong-driver-names",
"title": "USB exFAT does not work because BDM modules were not renamed into POPStarter's driver names",
"symptom": "FAT32 USB works, but exFAT USB is not detected by POPStarter.",
"likelyCauses": [
"bdm_assault.irx not renamed to usbd.irx",
"usbd_bd_assault.irx not renamed to usbhdfsd.irx",
"Files placed only in SYS-CONF and not mc?:/POPSTARTER",
"Using BDM for internal HDD exFAT expectation"
],
"mitigation": "Place bdm_assault.irx as mc?:/POPSTARTER/usbd.irx and usbd_bd_assault.irx as mc?:/POPSTARTER/usbhdfsd.irx. Keep internal HDD POPS data on APA/PFS.",
"sourceIds": [
"bdm-assault",
"user-notes"
],
"confidence": "high",
"verificationStatus": "verified-primary"
},
{
"id": "multi-disc-vmc-placement",
"title": "Multi-disc swap or shared VMC does not work",
"symptom": "Later discs cannot find the disc set, or each disc creates separate saves.",
"likelyCauses": [
"DISCS.TXT missing from one or more disc support folders",
"VMCDIR.TXT not placed in later-disc folders",
"VMCDIR.TXT points at a title instead of the first disc VCD filename",
"Filenames differ from the actual VCD names"
],
"mitigation": "Put DISCS.TXT in every disc support folder and VMCDIR.TXT in later-disc support folders. List exact VCD filenames, one per line.",
"sourceIds": [
"user-notes",
"shaolin-bitbucket-wiki"
],
"confidence": "medium",
"verificationStatus": "verified-hardware-user"
},
{
"id": "popsloader-folder-separation",
"title": "POPSLoader starts incorrectly because its support folder is misplaced",
"symptom": "POPSLoader launches to a blank screen, cannot list games, or loses expected UI/resources.",
"likelyCauses": [
"POPSLDR folder not beside POPSLOADER.ELF",
"POPSLoader paths mixed with original POPStarter OPL DB paths",
"Fork-only settings assumed to work in original POPSLoader"
],
"mitigation": "Keep POPSLOADER.ELF and the POPSLDR folder together under the POPSLoader app folder, and document fork-specific behavior separately from original POPStarter core.",
"sourceIds": [
"popsloader-el-isra",
"popsloader-fork-ripto",
"user-notes"
],
"confidence": "high",
"verificationStatus": "verified-cross-source"
},
{
"id": "popsloader-fork-bdma-mode",
"title": "POPSLoader fork device missing because BDMA mode is wrong",
"symptom": "USB/MX4SIO/MMCE games do not appear or launch from the fork.",
"likelyCauses": [
"BDMA disabled",
"Wrong single active BDMA mode selected",
"mc0 missing"
],
"mitigation": "Use mc0, enable BDMA for non-HDD devices, and select only the device mode being used.",
"sourceIds": [
"popsloader-fork-ripto"
],
"confidence": "high",
"verificationStatus": "verified-primary"
}
]