Shinra CC

Quick reference

Run these buttons in the import dialog, in this order, after the bad import finishes:

1. Test API Connection (token mode only)
2. Fetch and Import (or Import in paste/upload modes)
3. Copy override stubs
4. Export pack index
5. Download log

You do not need to touch the Index Dumps (Dev) panel. That panel is a maintainer tool for auditing Foundry's compendium ID fields and is not relevant to a player bug report. If you have debug log level on you will see the disclosure toggle for it; leave it collapsed.

Five steps in detail

Step 1 of 5: Test API Connection

When: Token mode only. Skip if you are importing via paste or upload.

Where: The button is in the Element Token tab of the import dialog. Click it before you run the actual import.

Why we need it: This confirms that the module can reach api.herolab.online with the user token you provided, before it tries to fetch the character. If your user token has expired or the HLO API is having an outage, this is the step that surfaces it. Knowing the API side is clean rules out a whole class of phantom bugs and tells me that the issue is downstream in the parser, the matcher, or the builder.

What to attach: Note in the issue whether this step passed or failed. If it failed, copy the exact error message into the issue. There is no file to attach for this step.

Step 2 of 5: Fetch and Import (or Import)

When: Always.

Where: The big primary button at the bottom of the dialog. Label is "Fetch and Import" in token mode and "Import" in paste/upload modes.

Why we need it: This is the actual import that produced the bad result. Run it normally, let it finish to completion, and do not close the dialog. The next three steps all read from the state the dialog accumulated during the import.

What to attach: Nothing yet. The artifacts come from steps 3 through 5. Just make sure the import has actually completed (the spinner stops and the dialog returns to its idle state) before you continue.

Step 3 of 5: Copy override stubs

When: Only if the dialog shows a Copy override stubs button after the import. This button only appears when the matcher could not resolve one or more items (the log shows warn or error entries for unmatched items).

Where: Under the conversion-log header, next to the log-count summary, only when there are unresolved items.

Why we need it: This is the matcher's "I could not figure out what this HLO item maps to in your Foundry compendiums" list, formatted as drop-in entries for the override table. It tells me exactly which HLO items the matcher missed, what slug it tried, what name it had, and what compset it came from. With this list I can hand-curate the override table without having to recreate your portfolio on my end.

What to attach: Click the button, paste the result into the issue body inside a fenced code block (triple backticks). If there is no Copy override stubs button, note "no unmatched items" in the issue and move on.

Step 4 of 5: Export pack index

When: Always.

Where: Visible when log level is set to debug. Switch the radio at the top of the conversion log to Debug to reveal the developer toolbar.

Why we need it: The pack index is a JSON dump describing every Foundry compendium your install can see, including PF2e, SF2e, and any system modules you have enabled. The matcher uses this exact dump at import time to decide which item to attach for each HLO entry. The reason I need YOUR copy of it is that Foundry compendium content shifts between system versions and modules; the index pins down what was actually available on your install when the bad import happened. Without this I am guessing at your environment.

What to attach: The downloaded .json file. Drop it into the issue as an attachment (drag-and-drop works in the GitHub issue editor).

Step 5 of 5: Download log

When: Always. This is the single most important attachment.

Where: Visible when log level is set to debug. Same toolbar as the pack-index button.

Why we need it: The conversion log is the same content you see in the dialog, exported as a .txt file. It records every parser decision, every matcher hit and miss, every builder mutation, and the exact failure point. Reading it back I can usually find the bad import within thirty seconds, and from there it is a normal debugging session. This is the file that lets me reproduce your bug on my desk.

What to attach: The downloaded .txt file.

Bonus attachments (optional but very helpful)

If you can also attach either of the following, it speeds things up significantly:

• The HLO portfolio JSON for the character you were importing. Paste mode and upload mode use this directly; in token mode you can grab it from Hero Lab Online via the standard portfolio-export path.
• The element token you used for the import (token mode only). The token is short-lived and bound to a single character, so pasting it into a GitHub issue is fine; I will use it once to reproduce and then it expires.

Either of these lets me run your exact failing import on my install rather than reverse-engineering it from the log.

What goes in the issue body

Roughly:

**System:** PF2e or SF2e (and version, if you know it)
**Foundry version:** V13.xxx or V14.xxx
**Module version:** check the version badge in the lower-right of the import dialog
**Import mode:** Token / Paste / Upload
**What you expected:** one sentence
**What happened:** one sentence

**Step 1 (Test API Connection):** passed / failed [+ error if failed]
**Step 3 (Override stubs):**
```
(paste the copy-button output here, or write "no unmatched items")
```

Attachments:
- pack-index-...json (step 4)
- hlo-import-log-...txt (step 5)
- [optional] HLO portfolio JSON
- [optional] element token

You do not have to use that template literally; just hit the headlines.

What NOT to send

• Screenshots of the dialog or the conversion log. I cannot grep a screenshot. The downloaded .txt log has everything the dialog showed, in a form I can search.
• Index Dumps output. Not relevant to player bug reports. Those buttons (under the collapsible Index Dumps panel) are maintainer-only tools for auditing Foundry's compendium ID fields when seeding the override table. The pack index from step 4 is what tells me about your environment.
• Foundry world saves or world data. I do not need (or want) your world. The pack index is the only environment data I need.

One last note

This is a five-step workflow for what is "ship me a bug report." That is intentional. The information surface of a failed import is large, and every time a player skips a step I end up asking for it later. Doing them in one pass while the dialog is still open in front of you is the path of least total effort for both of us.

Thank you for reading this far, and thank you for filing the bug report at all. Every fix in this module exists because someone took the time to tell me something was wrong. Keep them coming.

- Shinra CC