While I was working through the Install Guide, I ran into a small issue. It was pretty easy to work around, but here’s what it was and how to fix it, in case someone else runs into the same problem.


At the Checking Your Installation step in the install guide, it has readers run the groundstation command:

fprime-gds -g html -r <path to fprime checkout>/Ref/build-artifacts

I was getting an error, and then the flask application would exit.

[ERROR] Dictionary version  is not in supported range: 0.0.0-9.9.9. Please upgrade fprime-gds.

Root Cause

Before I began, I decided to fork the F-prime GitHub repository, in case I needed to make any file changes while doing the tutorials.

GitHub fork repository form, with an arrow highlighting the 'Copy the master branch only' checkbox.GitHub fork repository form. Not the "Copy the master branch only" checkbox, selected by default.

This is where I made an error. By forking with only the master branch, I did not receive the release tags in my fork.

After running generate and build…

fprime-util generate
fprime-util build

…I ended up with Ref/build-artifacts/Darwin/dict/RefTopologyAppDictionary.xml as would be expected, but on line one we have a problem:

<dictionary topology="Ref" framework_version="7cb9feed0" project_version="7cb9feed0">

fprime-gds wants to compare the framework_version property of this dictionary file to make sure it is compatible with this version of gds, but it doesn’t know how to compare a git commit SHA to the semantic version release tag.

A correct dictionary file would look like this, where 3.1.0 is the latest release of F-prime:

<dictionary topology="Ref" framework_version="3.1.0-9-g7cb9feed0" project_version="3.1.0-9-g7cb9feed0">

Work-around / Fix

All I needed to fix this was to pull down the git tags from the upstream repo.

$ git remote add upstream https://github.com/NASA/fprime/
$ git fetch upstream 
remote: Enumerating objects: 22769, done.
remote: Counting objects: 100% (16900/16900), done.
remote: Compressing objects: 100% (163/163), done.
remote: Total 22769 (delta 16776), reused 16778 (delta 16735), pack-reused 5869
Receiving objects: 100% (22769/22769), 18.89 MiB | 10.20 MiB/s, done.
Resolving deltas: 100% (21179/21179), completed with 734 local objects.
From https://github.com/NASA/fprime
 * [new branch]          devel                             -> upstream/devel
 * [new branch]          master                            -> upstream/master
 * [new branch]          release/documentation             -> upstream/release/documentation
 * [new branch]          revert-1553-feat/mermaid-deframer -> upstream/revert-1553-feat/mermaid-deframer
 * [new branch]          update/add-ref-ini                -> upstream/update/add-ref-ini
 * [new branch]          update/autodocs-null-commit-fix   -> upstream/update/autodocs-null-commit-fix
 * [new branch]          update/fix-tutorial-cmd-seq       -> upstream/update/fix-tutorial-cmd-seq
 * [new branch]          update/lgtm-fix                   -> upstream/update/lgtm-fix
 * [new branch]          update/linux-uart-refactor        -> upstream/update/linux-uart-refactor
 * [new branch]          update/sqls                       -> upstream/update/sqls
 * [new branch]          update/update-readme              -> upstream/update/update-readme
 * [new branch]          workaround/cycle-fpp              -> upstream/workaround/cycle-fpp
 * [new tag]             NASA-v1.00                        -> NASA-v1.00
 * [new tag]             NASA-v1.01                        -> NASA-v1.01
 * [new tag]             NASA-v1.10                        -> NASA-v1.10
 * [new tag]             NASA-v1.2                         -> NASA-v1.2
 * [new tag]             NASA-v1.3                         -> NASA-v1.3
 * [new tag]             NASA-v1.3.1                       -> NASA-v1.3.1
 * [new tag]             NASA-v1.4                         -> NASA-v1.4
 * [new tag]             NASA-v1.5.0                       -> NASA-v1.5.0
 * [new tag]             NASA-v1.5.1                       -> NASA-v1.5.1
 * [new tag]             NASA-v1.5.2                       -> NASA-v1.5.2
 * [new tag]             NASA-v1.5.3                       -> NASA-v1.5.3
 * [new tag]             v2.0.0                            -> v2.0.0
 * [new tag]             v2.0.1                            -> v2.0.1
 * [new tag]             v2.1.0                            -> v2.1.0
 * [new tag]             v3.0.0                            -> v3.0.0
 * [new tag]             v3.0.0-RC1                        -> v3.0.0-RC1
 * [new tag]             v3.0.0-RC2                        -> v3.0.0-RC2
 * [new tag]             v3.1.0                            -> v3.1.0

After running fprime-util build again, the new version of the dictionary has the correct tags.

To make this fix permanent for the forked GitHub repository, you’d still need to upload the tags to github.

git push origin [tag]


How did I arrive at the fix?

Again, here’s the error message:

[ERROR] Dictionary version  is not in supported range: 0.0.0-9.9.9. Please upgrade fprime-gds.

Because it talks about upgrading, I checked the repository’s requirements.txt to see what version of fprime-gds was in use.

$ grep fprime-gds ./requirements.txt

At the time, this was a patch version behind the latest fprime-gds, but that didn’t seem to account for the error. The version was a match to the declared dependencies.

So I searched fprime-gds repository for the error message and found the line where it was declared.

The one place it was used didn’t make a lot of sense to me, so I did a git blame on the error message to find the commit where it was introduced.

The commit message says something about “dictionaries”. I googled around a bit for fprime and dictionaries and the “Ref” app, and eventually found the filename of the dictionary. I’m missing some of my search history here for writing this post because I was using multiple computers.

Since the framework version was on the top line, and I’d already seen the code in GDS that was validating the version number, it immediately stood out that it was not the right format, and I recognized that it was getting invalid output from git because it didn’t have tags.


There may be an actual bug here since fprime-utils can generate build output that is not recognizable to fprime-gds. Or maybe it’s just user error since I accidently removed the release tags from my source control history.

I may report this once I get a better sense of what repository would “own” this bug. In the meantime, this is my bug report. ;)