Troubleshooting

Troubleshooting

TLDR

Most troubleshooting gets easier when you answer three questions first:

1. Are my versions compatible?
2. Is this a setup or content issue, or is it happening everywhere?
3. Did this begin after an update or migration?

If you check those first, you will solve many problems faster, and when you do need help, you will be able to explain the issue much more clearly.

This page is here to help when the SW5e Module for FoundryVTT is not behaving the way you expected.

The goal is not to overwhelm you with technical language. Instead, this page helps you narrow the problem down, check the most likely causes first, and decide whether you are dealing with:

• a version mismatch
• a setup issue
• a content issue
• an older migrated actor or item
• or a real module bug

What this page covers

This page will help you:

• check the most common causes of module problems first
• recognize several common symptom patterns
• gather useful information before asking for help
• decide whether the problem belongs to the SW5e Module, the DND5e system, or FoundryVTT core

If your question is really about FoundryVTT core functionality such as scenes, tokens, permissions, user roles, journals, or general system setup, use the Foundry Discord, Baileywiki, or Encounter Library instead.

Start here first

Before digging into a specific symptom, check these five things:

1. your FoundryVTT version
2. your DND5e system version
3. your SW5e Module version
4. whether you are using a public release or testing work in progress
5. whether the problem is happening on one item or actor or across the whole world

The most important rule

Always check the project’s README and Release Notes before assuming a guide matches your exact setup.

If something in the wiki does not match what you see on screen, a version difference is one of the first things to rule out.

A fast way to classify the problem

When something goes wrong, ask yourself which of these feels most true:

• “This only affects one custom item or actor.”
  That often points to a setup or content issue rather than a module-wide bug.

• “This changed after an update.”
  That often points to compatibility, migration, or a behavior change between releases.

• “This is happening everywhere.”
  That may point to compatibility problems, missing dependencies, or a broader module issue.

• “This seems like a normal Foundry question, not an SW5e question.”
  That likely belongs to general Foundry support instead.

That simple sorting step saves a lot of time.

Symptom: my blaster does not show a Reload control

Start here:

• confirm the actor is a supported character or npc
• confirm the item is actually the weapon being used, not a duplicate shell or older test copy
• compare the weapon to a fresh compendium example
• confirm the weapon is using the current managed blaster setup, including item uses and a compatible ammo type

If a built-in or freshly imported version works and your older world copy does not, the problem is probably in the copied item setup rather than in the sheet itself.

Symptom: I used Attack, Rapid, or Burst and got a private Reload card

That usually means the workflow is doing the right thing.

The private Reload card is sent when a supported managed blaster:

• has 0 remaining shots
• or does not have enough remaining shots for that activity’s ammo cost

The activity is stopped before it consumes anything, and the private card is sent only to the actor’s owners and GMs.

If that result surprised you, check:

• whether the weapon still has the remaining uses you thought it had
• whether the activity cost is higher than a normal attack because it is a Rapid or Burst use
• whether the actor has compatible ammo in inventory for the Reload step

Symptom: my starship does not have a Crew tab anymore

That is expected in the current workflow.

The old Crew tab was removed. Crew management now lives on the Core tab of the starship sheet. If you are looking for a starship based on older screenshots or older instructions, this is one of the most common changes to know about.

Use Starship Sheet Guide for the current sheet layout.

Symptom: my starship status icons or System Damage look wrong

Start here:

• confirm the actor is actually using the current starship workflow
• compare the actor to a newer working starship if possible
• check whether the issue is on the sheet, the token HUD, or both
• check whether the actor is older migrated content

Remember that several starship combat states now interact:

• System Damage
• Destruction Saves
• Used
• Slowed
• other starship conditions

If the problem is specifically about how those states are meant to work, use Starship Combat, Conditions, and System Damage as well as this page.

Symptom: my theme, icons, or dropdowns look wrong

Start here:

• remember that selectable SW5E theme modes are removed in the 1.4.0 feature set — use Foundry’s own Light/Dark appearance settings for chrome
• check Themes and Appearance for retained branding (Pause, lightsaber headers, logos)
• reload the browser session if an open sheet still looks stale after an update
• if a control looks broken rather than merely unthemed, compare another supported sheet before assuming a theme bug

Symptom: powers or points do not look right

If your issue involves Force powers, Tech powers, Force Points, Tech Points, or related powercasting behavior, start with these checks:

• confirm the actor is actually a power-using actor
• confirm the expected powers are attached to that actor
• compare the actor to another known-good actor if possible
• check whether the actor’s powercasting configuration matches what you think it should be
• check Force/Tech point discounts on the Power Point dialogs if costs look unexpectedly low
• for Powers Known, remember Free Learn does not count and .known.value is prepared, not an Active Effect target

If the actor uses an advanced powercasting setup, review Powercasting Configuration and Overrides and Attribute and Active Effect Keys.

Symptom: a weapon property is not behaving the way I expected

If your problem involves a weapon, attack behavior, or a property such as Keen, Reload, Rapid, or Burst, check the item itself before assuming the sheet is broken.

Start by checking:

• whether the weapon actually has the property you think it has
• whether the property includes a numeric value
• whether the activity or action setup matches the behavior you expect
• whether a fresh compendium example behaves the same way

If a built-in example works and your custom version does not, the problem is often with the content setup.

Symptom: older content behaves differently than new content

If something only feels wrong on older actors, items, or starships, migration should be high on your list of suspects.

Common signs:

• the problem affects older content but not newly created content
• the problem appeared after a major update
• the document looks partially correct but not fully functional
• a fresh import works better than the older copied version

In those cases, compare the older content to a newly created or freshly imported example.

When the issue is probably your content, not the module

A lot of real problems are actually content-authoring problems.

This is especially likely if:

• only one custom item is affected
• only one homebrew power or weapon behaves strangely
• a duplicated item stopped working after you changed several fields
• a built-in compendium example still works correctly

If that sounds like your situation, compare the content to a built-in example before reporting a bug.

A simple troubleshooting workflow

If you are not sure where to begin, use this order:

1. check your versions
2. read the latest README and release notes
3. see whether the problem affects one thing or many things
4. compare the broken thing to a known-good built-in example
5. decide whether the issue is:
   • content
   • compatibility
   • migration
   • or module behavior
6. test again after changing only one variable at a time
7. if the problem still looks real, gather bug-report details

What information to gather before reporting a bug

If you need help or want to report a likely bug, collect these details first:

• your FoundryVTT version
• your DND5e version
• your SW5e Module version
• whether you are using a stable public release or testing newer work
• whether the issue affects one actor or item or many
• whether the content is newly created or older migrated content
• what you expected to happen
• what actually happened
• the exact steps needed to reproduce it

How to describe the problem clearly

A good bug report usually sounds like this:

• “On Foundry X, DND5e Y, and SW5e Module Z, this happens...”
• “I tested it on a built-in example and a custom example...”
• “It only affects older migrated starships...”
• “It only happens when using this property or activity setup...”
• “Here are the exact steps...”

That kind of report is much easier for maintainers to understand than “it broke.”

When to use outside Foundry help instead

Use the Foundry Discord, Baileywiki, or Encounter Library if the issue is really about:

• scene setup
• token controls
• permissions
• journal use
• basic compendium use as a Foundry feature
• general Foundry troubleshooting not specific to SW5e Module behavior

This wiki is here to help with the SW5e Module itself, not to replace broader Foundry learning resources.

Related pages

Depending on the problem, one of these pages may be more specific and more useful:

• Sheets & Features
• Blaster Reload and Ammo Use
• Themes and Appearance
• Starship Sheet Guide
• Starship Combat, Conditions, and System Damage
• Weapon Properties Support
• Homebrew and Content Authoring
• Compatibility & Limitations
• FAQ