Issues with the "Hello World" tutorials and how to fix them


I’ve been following two quick-start guides today, and I ran into a bunch of issues. All of them were fixable in the end, and I managed to make the tutorial work, and I thought I’d document my steps here, in case someone else has the same problems.

For the dfinity devs, was I doing something wrong or are there any more up to date tutorials that I should follow?

The tutorials I was following:

I’m working on a clean install of Ubuntu 20.04, with all the dev-tools, dependencies, node, cmake etc. installed.

:~/work/dfinity/hello$ dfx --version
dfx 0.7.2

The first step in the tutorial that differed for me: I was getting two missing dependencies warnings at npm install.

:~/work/dfinity/hello$ npm install
npm WARN @dfinity/agent@0.9.1-beta-1 requires a peer of @dfinity/candid@^0.9.1-beta-1 but none is installed. You must install peer dependencies yourself.
npm WARN @dfinity/agent@0.9.1-beta-1 requires a peer of @dfinity/principal@^0.9.1-beta-1 but none is installed. You must install peer dependencies yourself.

When I ignored the warnings, the next step failed with errors:

~/work/dfinity/hello$ dfx build
Building canisters...
Building frontend...
The post-build step failed for canister 'ryjl3-tyaaa-aaaaa-aaaba-cai' with an embedded error: The command '"npm" "run" "build"' failed with exit status 'exit code: 1'.


ERROR in ./node_modules/@dfinity/agent/lib/esm/actor.js 5:0-38
Module not found: Error: Can't resolve '@dfinity/candid' in '/home/ubuntu/work/dfinity/hello/node_modules/@dfinity/agent/lib/esm'


ERROR in ./node_modules/@dfinity/agent/lib/esm/actor.js 7:0-47
Module not found: Error: Can't resolve '@dfinity/principal' in '/home/ubuntu/work/dfinity/hello/node_modules/@dfinity/agent/lib/esm'

I fixed these errors with the following commands:

:~/work/dfinity/hello$ npm install @dfinity/candid

:~/work/dfinity/hello$ npm install @dfinity/principal

After this dfx build / dfx deploy worked as intended, and deployment was successful. I verified that the deployment worked with this:

:~/work/dfinity/hello$ dfx canister call hello greet everyone
("Hello, everyone!")

The next problem was when trying the web interface. I loaded the url of the assets canister ( in my case) in 3 different browsers and all three were showing the same error in the console

Uncaught (in promise) Error: Fail to verify certificate
    at Et (index.js:2)
    at async r (index.js:2)
    at async HTMLButtonElement.<anonymous> (index.js:2)

The “click me!” button was not working.

After reading through some topics on this forum, I found a fix - add “agent.fetchRootKey();” in hello_assets/src/index.js, before performing the hello.greet call.

Listing for my index.js after the edit:

import { Actor, HttpAgent } from '@dfinity/agent';
import { idlFactory as hello_idl, canisterId as hello_id } from 'dfx-generated/hello';

const agent = new HttpAgent();
const hello = Actor.createActor(hello_idl, { agent, canisterId: hello_id });


document.getElementById("clickMeBtn").addEventListener("click", async () => {
  const name = document.getElementById("name").value.toString();
  const greeting = await hello.greet(name);

  document.getElementById("greeting").innerText = greeting;

After rebuilding and redeploying the sample app seems to work properly, and I get the greeting displayed in the web interface as well.

Perhaps something got broken during an update, and someone forgot to update the tutorials?


just wanted to mention (hopefully it’s useful to know) that I had the same problems when following the tutorial as well, with node and dfx up-to-date.
Your suggested fixes also worked for me, so thank you :slight_smile:

More generally, the backend tutorials worked fine but the ones dependent on frontend stuff, such as the linkedUp did not display properly.


I’m sure others would appreciate contributions to the docs repo: GitHub - dfinity/docs: Documentation for writing code for the Internet Computer

I was able to contribute fixes to one of the Rust tutorials here, so they may not all be in the same place: docs: fix path to candid file in Rust quick start by paulyoung · Pull Request #101 · dfinity/cdk-rs · GitHub

Hey folks, as noted, the agent.fetchRootKey() solution works, but it doesn’t feel great and it’s honestly a bit of a footgun.

In general I welcome PR’s to the docs, but I’m going to commit to fixing the problem properly in the next dfx release and then updating the docs and dfx new template with a nicer solution. This will also come with enhanced type inference for your services


(Foot-shooting prevention agreement

If I may suggest. . . . It sounds like a lot of the problems and challenges that people are having are “dev-ops” problems. Things work fine on the developer’s machines because they already have all of the libraries and dependencies installed. But, not so, us in the rest of the world. Maybe you could create a couple of docker containers that could be down loaded and spun up by would be developers such as myself. They could be pre-installed with the right mix of libraries, versions, dependencies etc. Then if things change you could create new versions of the containers, and tell everyone to switch to the new version when appropriate. As long as you are running the right container version Number, everything should work perfectly, and save everyone a lot of time and trouble. Yes, you may have to teach people to install Docker, but that’s easier than trouble shooting each person’s dev rig, individually.

1 Like

Circling back to this - we released dfx 0.7.7 with some fixes to code generation that will resolve the hello world tutorials while also enhancing the developer experience. After gathering feedback, we have decided to skip promoting 0.7.7, and to treat these changes as a breaking change that will go out as 0.8.0, which will incorporate some of the feedback on 0.7.7 that we received. Look forward to an update soon!


Let’s be clear, when you say “breaking change” you mean that this update brings up problems and should be avoided? Which release should we use, if any, until 0.8.0 comes out?

The breaking change would be that if you had a project from 0.7.2 or prior, there’s a decent chance it would require changes to the build config to keep running.

0.8.0 is the next version to get on. I’ve updated the docs to reflect 0.8.0 changes, and we will be promoting it today as the most up-to-date version