# 7. UPM Package Pitfalls
Part of [[Authoring Custom UPM Packages]]. Prev: [[6. Worked Example Class Toolkit Release]].
> [!warning] Code not compiled
> Fixes refer to files in this series, which were not imported or compiled. See the hub for open questions.
## Authoring
| Symptom | Cause | Fix |
|---|---|---|
| Scripts in the package do nothing, no errors | No `.asmdef` covers them ("the Editor ignores scripts inside the Packages folder unless they're part of an assembly definition") | Put code under `Runtime/` or `Editor/` with their asmdefs; new top-level code folders need their own asmdef |
| Package compiles in the Editor, player build fails | `using UnityEditor...` in a runtime script outside `#if UNITY_EDITOR` (the original `NPCConversationManager.cs` had exactly this) | Move Editor code to `Editor/`, or wrap both the `using` and the code in `#if UNITY_EDITOR`; build a non-dev player before every release |
| `The type or namespace 'TMPro' could not be found` | Runtime asmdef lacks the TextMesh Pro / uGUI references | Add them in the asmdef Inspector (*Assembly Definition References*) and `com.unity.ugui` to `dependencies` |
| Students' scripts cannot see package types | `autoReferenced` off, or types are `internal` | Keep `autoReferenced: true` for class packages; make the intended API `public` |
| Package cannot use a class from the student's project | Packages cannot reference `Assembly-CSharp` | Invert the dependency: interfaces/events in the package, implementation in the project (e.g. `IDialogueInput`, `DialogueEvents`, the telemetry bridge staying in `Assets`) |
| `Environment.GetCommandLineArgs` (or similar) fails to compile in a project | A global-namespace class in the package hides a `System` type | Put every package type in a namespace (`PittmanClass.Dialogue`) |
| Custom inspector errors after adding namespace `...Editor` | `Editor` now resolves to your namespace | Write `UnityEditor.Editor` explicitly |
| Legacy `Input` exceptions in new projects | Project uses Input System only | Abstract input (`IDialogueInput`), use `ENABLE_INPUT_SYSTEM` / Version Defines |
| Package writes files and they vanish or error | Tool wrote into the package folder (read-only cache for students) | Editor tools write to `Assets/...` (like `Assets/DialogueLayouts`) |
## GUIDs and samples
| Symptom | Cause | Fix |
|---|---|---|
| "Missing script" / broken prefab references after install | `.meta` files not committed, or files copied outside Unity so new GUIDs were generated | Commit every `.meta`; move files in the Project window; never regenerate metas |
| Old student scenes lose components after migrating | Package scripts got new GUIDs | Keep the original `.meta` files when moving scripts into the package (part 3) |
| Duplicate class / duplicate GUID errors | Old `Assets/Scripts/Grok.Dialogue` still present next to the package | Delete the old folder first (migration steps, part 6) |
| No *Import* button for the sample | `samples` missing in `package.json`, wrong `path`, or folder not in the repo | Check `path` matches `Samples~/<Folder>` exactly (case-sensitive on Git hosts) |
| Sample appears in the Project window inside the package and compiles | Folder named `Samples` (no tilde) in a Git-distributed package | Rename to `Samples~` and update `path` (hub open question) |
| Sample imported into the dev project duplicates GUIDs | Imported the sample back where it was authored | Test samples only in a separate project |
## Distribution
| Symptom | Cause | Fix |
|---|---|---|
| "Unable to add package ... git" | Git not installed / not on `PATH`, or Git older than 2.14.0 | Install Git for Windows; `git --version` in a new terminal; restart Unity Hub |
| Install fails with `#tag?path=` | Wrong order | `?path=/Packages/<name>` **before** `#tag` |
| "revision not found" with a commit id | Short SHA | Use the **full** 40-character hash, or a tag |
| Students have different code with the same URL | Branch URL (`#main`) locked at different commits | Give tag URLs only |
| Fix released but students still have the bug | Lock file pins the old commit | Students re-install with the new tag; announce it |
| Two different "1.0.0" in the class | A tag was moved or deleted and re-created | Never move tags; release `1.0.1` |
| Private repo install fails over HTTPS | No interactive credentials in the Package Manager | Public repo, or SSH / credential helper (part 5) |
| Images in the sample are tiny text files | Git LFS pointer files (shallow clone, or no LFS client) | Keep package files out of LFS |
| A package's `package.json` lists a Git URL dependency and fails | Git dependencies are allowed only in the project manifest | Ask students to add both packages to their manifest |
## Naming and versioning
| Mistake | Why it hurts | Fix |
|---|---|---|
| Name contains `unity` (e.g. `com.unityclass.tools`) | Not allowed by the naming rules | `com.pittmanclass.tools` |
| Uppercase or spaces in `name` | Invalid package name | Lowercase, `-`, `_`, `.` only |
| `version` in `package.json` differs from the tag | Package Manager shows one version, students quote another | Bump `version` in the same commit you tag |
| Renamed a public field students' prefabs use, released as a patch | Serialized data is part of the API surface; this is breaking | Add `[FormerlySerializedAs]`, or release a major version |
| Staying at `0.x` forever | Students cannot tell stable from experimental | `1.0.0` once you will keep the API for a semester |
## Teaching pitfalls
- **Students "fixing" package code.** They cannot (read-only cache), so they will copy scripts into `Assets` and get duplicate classes. Teach the extension points (events, interfaces, ScriptableObjects, samples) on day one.
- **Too many packages.** Each package is another URL and another version to explain. Two or three packages per course is plenty.
- **Release mid-assignment.** Announce updates between assignments; lock files protect students only if you do not ask them to update during a deadline week.
## Sources
- Assembly definitions for packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-asmdef
- Naming (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-structure/cus-naming
- Git dependencies (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/upm-git-dependencies/upm-git
- Package versioning (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/upm-semver
- `FormerlySerializedAsAttribute` (6000.5): https://docs.unity3d.com/6000.5/Documentation/ScriptReference/Serialization.FormerlySerializedAsAttribute.html
- Related: [[1. Serialization Meta and Gitignore]], [[2. Git LFS]], [[Version Control]]