Troubleshooting

Symptoms first, since that is what you have when you arrive here.

Nothing happens when I call Start

The tutorial is on the server. The kit asserts TutorialKit is client only on build, so if you see no error at all, the script probably is not running. Check that it is a LocalScript and that it is somewhere that runs, such as StarterPlayerScripts.

The target GuiObject was nil at build time. FocusUI.to(playerGui.HUD.ShopButton, ...) evaluates that path immediately, before the HUD may exist. Use WaitForChild.

Replicate = true without a server. build yields waiting for a RemoteEvent that never appears, because TutorialServer:Start() was never called. Either start the server module or drop the flag.

The dim overlay has a seam along the highlight

You are running an older build, or you rebuilt the overlay yourself out of four semi-transparent frames.

Overlapping semi-transparent frames stack their alpha, and the overlap renders as a line. Padding does not fix it, because the problem is overlap and not spacing. The kit puts the panels in a CanvasGroup, which flattens them into one image before applying transparency. See Guidance tools.

A listener from an earlier step keeps firing

The connection was not registered on the step Janitor.

-- Wrong: outlives the step
Custom.new(function(context)
	SomeService.Fired:Connect(onFired)
end)

-- Right
Custom.new(function(context)
	context.Janitor:add(SomeService.Fired:Connect(onFired), "Disconnect")
end)

The camera is stuck in scriptable mode

A tour ended without restoring, which the kit goes out of its way to prevent. Two things to check:

• Are you calling Cinematic alongside your own camera code in the same step? Two owners will fight.
• Did you create a CameraTour yourself with create and never Destroy it? If you create it, you own it.

My dialog never appears

No renderer bound. Dialog.new only exists on the object createDialogs returns. If you are calling TutorialKit.Dialog.new, that is the wrong Dialog.

The renderer returned nil. That is the "could not open" signal, so the kit shows nothing. Check the early returns in your renderer.

The renderer drew into a ScreenGui that does not exist yet, or one whose DisplayOrder puts it under the spotlight overlay, which sits at 9700.

Type errors on request.Extra

You did not annotate the parameter.

-- Extra is never bound
TutorialKit.createDialogs(function(request) ... end)

-- Extra is GuideDialog from here on
TutorialKit.createDialogs(function(
	request: TutorialKit.DialogRequest<GuideDialog>
) ... end)

Build errors

These all fire at boot, on purpose, so they never reach a player.

Message	Cause
TutorialKit is client only	build called from the server
TutorialKit.build needs at least one step	Empty step list
TutorialKit step order N is duplicated	Two steps share an order number
TutorialKit step order must be a positive integer	Order was zero, negative or fractional
dialog needs at least one line	Empty Lines
dialog choice sets both Advance and GoTo	They contradict each other
dialog declares N choices but the renderer draws at most M	Exceeds the MaxChoices you declared

Runtime warnings

[TutorialKit] Unknown step N means a GoTo or a server SetStep named an order that no step carries. It warns rather than errors, so a step removed in a newer build cannot break an old client mid-session. If you see it in development, a GoTo is pointing at a step you renumbered.

Install problems

Packages is not a valid member of TutorialKit when using Wally usually means the shim was mapped as a folder path instead of the .lua file:

"TutorialKit": { "$path": "Packages/TutorialKit.lua" }

When using a git submodule instead, both entries are needed:

"TutorialKit": {
  "$path": "lib/tutorial-kit/src",
  "Packages": { "$path": "lib/tutorial-kit/packages.project.json" }
}

Unable to find package kartzrbx/tutorial-kit means the package has not been published yet, or your wally install ran before the first publish. Run wally install again after the registry lists the package at wally.run/package/kartzrbx/tutorial-kit.

Server requires pulling in ezvisualz

You required the facade instead of the server module.

-- Wrong on a server: drags in the spotlight, the pointer and ezvisualz
const TutorialKit = require(ReplicatedStorage.TutorialKit)

-- Right
const TutorialServer = require(ReplicatedStorage.TutorialKit.Server)