Microsoft MakeCode

Custom tutorial

I am trying to make a custom tutorial in MakeCode Arcade.
I have followed this video:
And I have followed this documentation:

When I do the steps for the Micro:Bit editor it work perfectly: see here

The problem is when I follow the exact same steps in MakeCode Arcade, it does not work.
When you load the tutorial you get an error message, “Please check your internet connection and check the tutorial is valid”
See here:

In the editor when you are previewing it, it works fine.
But when you click the “test” lab button, you get the same error.

Even stranger, if I load the tutorial using the GitHub URL, so it picks up the then the IDE does load correctly and it follows through with a tutorial from the file!

Not sure what I am doing wrong.
Is anyone else having this issue?

Thanks, Patrick

Ah, sorry about this! It’s a MakeCode bug that was introduced in the most recent version of Arcade. Non-README tutorials are broken in repositories with .ts files. For a quick fix, deleting the main.ts and test.ts files from your repository should allow the tutorials to load–we also have a fix from our end that we are hoping to ship soon!

Just tried removing the 2 files and that does not seem to fix it.
See here:

Hmm, okay a couple things here:

  1. You also need to delete the image.g.ts file, which unfortunately has to be through Github since it’s locked in the MakeCode view
  2. The markdown files need at least one tutorial step, or else we error out on loading

I made a copy of your repository with these changes and submitted a pull request here:

If you click “Merge” at the bottom it should update your files accordingly.

The last thing is, you may need pull these changes into your project (in and click “Create Release” on the Github view inside Arcade. We have several layers of caching, so it could be up to 20 minutes before changes are visible unless you create a release.

Hopefully this helps! (And we will definitely fix this ASAP so everything will work from the jump in the future)

That works.

I was also wondering, when you make a tutorial it only shows the block that you are using.
Is there a way to have that functionality to “reduce” the number of blocks students see in the regular IDE?


1 Like

Awesome! And we don’t have that for the sandbox experience, but you could create a one-step tutorial that uses “ghost” code snippets to specify which blocks show up in the toolbox, and the “lockedEditor” URL parameter to prevent students from exiting at the end of the tutorial.

(Additional documentation here:

Thanks so much.

One more question.
Since this is a bug that will be fixed, do you have a GitHub issue that I can track?


Hmm, so the fix is here:, but it won’t be available on the website proper until we do a release, which we don’t typically have a Github issue for. I’m happy to post on this thread post-release so you can verify that it is fixed, if that would be helpful!

Yes, thanks

1 Like

@Mr-Coxall This fix has been deployed and tutorials with .ts files should work as expected! Please let us know if there are any other issues