Flaky rdme update docs: Unexpected token Error

[hschmidtchen]

We are running the following command in our CI (multiple times a day):

npx -y rdme@10.4.0 docs upload ./docs --key=${README_API_KEY} --branch=v1

The job fails in about 20% of the pipeline runs with the following error on one of the uploaded files:

Unexpected token '<', "<!DOCTYPE "... is not valid JSON

The files have not changed in the past days in between the CI runs and yet we see this error from time to time.

I assume that there is an HTTP error thrown from the readme API that is not properly handled by the rdme lib.
Is there a way to debug this like turning on verbose debug logs for the rdme lib?
Knowing the kind of error would probably hint towards a possible solution.

Happy to provide more details if needed!

[urimerhav]

+1

[urimerhav]

also if I remove --key, while logged in, then we get "unexpected error"

[kanadgupta]

Hey folks! We shipped #1324 which should help with troubleshooting these kinds of errors going forward if you want to pull that into your workflows — that will process non-JSON errors more gracefully, making the debug logs more useful and the error a bit more human-readable.

We're aware of occasional 5xx errors when folks bulk upload lots of pages at once via our API. We have an internal ticket (CX-2187) tracking this. We'll keep this GitHub issue updated as we have updates.

If you could share a rough estimate of how many pages you're attempting to upload with a single rdme docs upload invocation, that'd be helpful for us so we can understand the scale of this issue. Thanks!

[kanadgupta]

also if I remove --key, while logged in, then we get "unexpected error"

@urimerhav mind opening a separate issue for this with details on the exact command workflow you're running and the error you're seeing?

[euan-purves-br-dge]

Hi @kanadgupta,

We've also been seeing this error when running a similar command.

rdme docs upload Documentation --key=${API_KEY}

In our case there are currently 66 markdown files in the Documentation directory, and it seems to happen sporadically after about 60 docs are uploaded successfully. I have noticed that the doc that the error happens on is often not the same one, and if I manually upload the same doc on it's own, the error is not thrown. Are we hitting a rate limit by trying to do so many docs at once?

From what I can tell, the rdme CLI v10 re-uploads everything if you pass in a directory, even if there are no changes to the docs.

I don't believe this happened in the older version (at least not in the old v8 CLI). From what I recall, the older CLI used to check if the remote doc was different to the local doc, and if the docs were the same, they would be skipped in the upload command.

Thanks!

[kanadgupta]

@euan-purves-br-dge apologies for the delay here.

This feature (i.e., comparing the local page content to the remote page content) would not always behave as expected so we removed it in v10. Now that ReadMe Refactored / rdme@10 is fully backed by git, we are exploring ways to re-introduce this functionality in a more resilient way, but I cannot promise any firm timelines at the moment.

[hschmidtchen]

@kanadgupta since the update you shared, our CI job has been very stable and I dont have any insights to share.
We are only uploading 6 docs, so really not a high amount and I assume there was a change on the readme API that fixed the problem for our use case.

Not sure about @euan-purves-br-dge and @urimerhav but from my perspective, this issue can be closed.